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PREFACE 



INTRODUCTION 

The iRMX® System Debugger is a memory-resident extension of the iSDM™ System 
Debug Monitor. The System Debugger gives you a static debugging tool that can recognize 
and display all iRMX objects. It enables you to examine your iRMX system interactively 
so you can find and correct errors. 



READER LEVEL 

This manual is intended for application engineers familiar with the concepts and 
terminology introduced in the iRMX® II Nucleus User's Guide or the iRMX® I Nucleus 
User's Guide and the system programmers implementing device drivers, object managers, 
and operating system extensions. 



MANUAL OVERVIEW 

This manual consists of the following chapters: 

Chapter 1 INTRODUCTION-This chapter describes the features of the 

System Debugger, illustrates how the System Debugger relates to 
EPROM-based debugging tools, and explains how to use the System 
Debugger. Read this chapter if you are going through the manual 
for the first time. 

Chapter 2 SYSTEM DEBUGGER COMMANDS-This chapter contains 

detailed descriptions of the System Debugger commands, presented 
in alphabetical order. When debugging your system, refer to this 
chapter for specific information about the format and parameters of 
the commands. 

Chapter 3 SAMPLE DEBUG SESSION-This chapter shows in a step-by-step 

fashion how to use System Debugger features. The chapter contains 
a sample debugging session showing how to use iSDM monitor and 
System Debugger commands to locate an application-code error, 
correct it, and test the change. Separate examples showing 
additional debugging techniques are also included. Use this chapter 
as a hands-on introduction to the System Debugger. 
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Appendix A 



Appendix B 



iSDM MONITOR COMMANDS--This appendix briefly describes 
the function of all basic iSDM monitor commands. Use this 
appendix as a quick reference to the iSDM monitor. For more 
information see the iSDM™ System Debug Monitor User's Guide. 

D-MON386 MONITOR COMMANDS-This appendix briefly 
describes the function of all basic D-MON386 monitor commands. 
For more information, refer to the D-MON386 Debug Monitor for 
the 80386 User's Guide. 



CONVENTIONS 

This manual uses the following format conventions: 
• User input appears in one of the following forms: 

as blue text 



as bolded text within a screen 



The text <CR> appears where you must enter a carriage return. When pressing the 
carriage return key, the text <CR> does not appear on the console. 

Although all syntax diagrams show uppercase letters (e.g., VR), you can also use 
lowercase letters. 

All numbers unless otherwise stated are assumed to be decimal. Hexadecimal numbers 
include the "H" radix character (for example, OFFH). 

The term "iRMX II" refers to the iRMX II (iRMX 286) Operating System. 

The term "iRMX I" refers to the iRMX I (iRMX 86) Operating System. 

The terms "iRMX" or "iRMX Operating Systems" when used by themselves, refer to 
both iRMX I and II, that is, the text applies equally to both operating systems. 



VI 
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iRMX® SYSTEM DEBUGGER 

OVERVIEW 



1 



1 .1 INTRODUCING THE iRMX® SYSTEM DEBUGGER 

When you develop application systems, you need debugging capabilities on your 
development system. Besides the iSDM™ System Debug Monitor, Intel provides the iRMX 
System Debugger (SDB) for debugging your iRMX-based application system. 



NOTE 

The remainder of this manual uses the term "monitor" to refer to the iSDM 
System Debug Monitor. 

The System Debugger is a memory-resident extension of the monitor; therefore, you must 
have the monitor if you have the System Debugger configured into your system. The 
monitor provides code disassembly, execution breakpoints, memory display, and program 
download capabilities. The System Debugger extends the monitor's disassembly functions 
by interpreting iRMX calls, data structures, and stacks. 

Monitor and System Debugger commands are entered in response to the iSDM Monitor's 
protected-mode prompt (..) or the iRMX I real mode prompt (.). When you invoke the 
monitor, both the operating system and your application system are frozen. As you use 
monitor commands to set breakpoints while the application code is executed, you can 
inspect system objects, change system call parameters and registers, and test changes. 
Refer to Appendix A for more information on iSDM Monitor commands and Appendix B 
for D-MON386 Monitor commands. 
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1 .2 SUPPORTING THE SYSTEM DEBUGGER 

To use the System Debugger, you must have one of the following hardware configurations 
with all the required support hardware: 

• An Intel Microcomputer connected to an 8086-, 80186-, 80188-, 80286- or 386™-based 
board 

• A terminal connected directly to an 8086-, 80186-, 80188-, 80286- or 386™-based board 

• An Intellec® Development System connected to an 8086-, 80286- or 386™-based board 

Besides the above hardware, you must have both of the following: 

• The EPROM portion of the iSDM System Debug Monitor 

• An iRMX operating system configuration 



1 .3 CONFIGURING THE SYSTEM DEBUGGER 

You cannot use the System Debugger until you include it in your system through the 
Interactive Configuration Utility (ICU). To include the System Debugger, begin by 
invoking the ICU. Next, provide the following information the ICU requires to configure 
the System Debugger: 

1. In the ICU's "Sub-Systems" screen, respond "yes" to the SDB prompt. 

2. In the ICU's "System Debugger" screen, set the interrupt level you want to use to 
invoke the monitor manually (by pressing a hardware interrupt button). 

To use the Non-Maskable Interrupt (NMI) for debugging device drivers, see the 
iRMX® II Hardware and Software Installation Guide or the iRMX® I Hardware and 
Software Installation Guide . 

For detailed information on configuring the System Debugger, consult the iRMX® II 
Interactive Configuration Utility Reference Manual or the iRMX® I Interactive Configuration 
Utility Reference Manual. 
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1 .4 INVOKING THE SYSTEM DEBUGGER 

You must enter the monitor to use the System Debugger. You can invoke the monitor in 
three ways: 

1. Use a hardware switch physically connected to the interrupt level you specified during 
configuration. Activating this switch halts the application system, saves the system's 
contents, and passes control to the monitor. 

2. Use the Human Interface DEBUG command. DEBUG loads your specified 
application program into main memory and transfers control to the monitor. 

3. Use the Bootstrap Loader DEBUG switch. When you specify this switch, the monitor 
comes up after the system is loaded but before the system starts running. The CS:IP 
points to the first instruction of the application system. At this point the system has not 
been initialized; therefore, you can run only monitor commands. Using the MAP286 
output (or MAP86 in iRMX I), you can identify where you want to insert breakpoints. 
(For more information on BIND, MAP, and OVL, see the 80286 Utilities User's Guide 
for iRMX® II Systems or the 86, 88 Utilities Reference Manual in iRMX I). Use the 
break address parameter in the monitor's GO (G) command to set breakpoints in the 
application system code. When you enter "G <CR>", the system starts and is 
initialized. The monitor is invoked when CS:IP reaches a breakpoint. For more 
information on booting with DEBUG, consult the iRMX® Bootstrap Loader Reference 
Manual. 

When you invoke the monitor, the application system stops running and all system activity 
freezes. The appropriate prompt appears (the ".." for the iSDM Monitor, or a single "." in 
iRMX I), and you can begin entering System Debugger and monitor commands to examine 
system objects. 
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1 .5 USING THE SYSTEM DEBUGGER 

The System Debugger uses monitor procedures to parse the command line and to output 
to the console; therefore, you run both System Debugger and monitor commands from the 
monitor. The syntax for System Debugger commands is a "V" or V followed by another 
letter, an optional space, and an optional parameter. 

The fifteen System Debugger commands (described in Chapter 2) fall into four categories: 

1. Eight commands extend the monitor memory display functions by displaying iRMX 
data structures and objects. 

2. Three commands extend the monitor disassembly functions by recognizing and 
displaying iRMX calls. 

3. Three commands add the ability to display features of the Message passing 
Coprocessor (MPC) (iRMX II only) . 

4. A help command provides a short description of all the commands. 

All commands either display information as hexadecimal numbers or try to interpret the 
information. If the System Debugger cannot interpret the information, it displays the 
actual hexadecimal value, followed by two question marks. 

iRMX II provides two features that enable you to leave the monitor without resetting your 
system: warm-start and CLI-restart. The warm-start feature reinitializes the system and 
returns control to the Human Interface at the login level. The CLI-restart feature deletes 
the current job then returns control to the Command Line Interpreter. Refer to Chapter 2 
for more information on these features (iRMX II only) . 



1.6 RETURNING TO YOUR APPLICATION 

Use the monitor's GO command (G) to resume execution of the application 

• When you finish debugging your application system with the System Debugger. 

• If you want to test the changes you made to the application code. 
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2.1 INTRODUCTION 

This chapter contains detailed descriptions of the iRMX System Debugger commands. 
Commands appear in alphabetical order, with the first occurrence of each command 
appearing in blue at the top of the page. A directory of the commands, divided into 
functional groups, precedes the command descriptions. 

This chapter uses the following conventions: 

• "CS:IP" is the Code Segment:Instruction Pointer--The pointer to the instruction that 
would be executed next if the application system were running. If you specify an IP 
value (one four-digit hexadecimal number) but not a CS value, the System Debugger 
uses the current CS as the default base. 

• "SS:SP" is the Stack SegmentrStack Pointer-The pointer to the current stack location. 

• Entering zero (0) as a value for an optional parameter is the same as omitting the 
parameter; the default value of the parameter is used. 

• All terminal examples assume that the iSDM System Debug Monitor is being used. 
Thus, example input lines show the iSDM monitor prompt ".." (or a single "." in 
iRMX I). 
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2.2 CHECKING VALIDITY OF TOKENS 

Many System Debugger commands use iRMX tokens as parameters or display tokens as 
part of the command output. The iRMX Operating Systems maintain tokens in doubly 
linked lists. When you enter a token as a parameter, the System Debugger checks the 
validity of the token by looking at the forward and backward links of the token. 

If one of the links is bad, the System Debugger generates an error message along with the 
standard command output. The token you enter as a parameter always appears as the 
center value in each line of the token display. The displays for forward- and backward-link 
errors are as follows: 

Forward link ERROR: 4111-->4E85 4111 <--4E85--> 4155 ?FFFF<--4155 

Backward link ERROR: 4111™>410F? 4111<--4E85-->4155 4E85<«4155 

Arrows to the left indicate backward links; arrows to the right indicate forward links. A 
question mark before or after a value signifies a forward or backward link error, 
respectively. 

If both links are bad, the System Debugger considers the token invalid. A token may also 
be invalid 

• if it belongs to an object in the deletion process 

• if an incorrect token is entered as a parameter in a system call 

• if a deleted or unused token is entered as a parameter. 

When the token is invalid, the System Debugger displays the following message: 



*** INVALID TOKEN *** 



A link error indicates that iRMX data structures have been corrupted. The most common 
reason for this problem is a task might have accidentally written over part of the system 
data structures. However, (in the case of the iRMX II Operating System) the iRMX II 
protection mode feature protects against such overwriting under normal circumstances. 
Data structure corruption can also occur if you are using the Non-Maskable Interrupt 
(NMI). The Nucleus may have been interrupted while it was setting up the links. (The 
NMI is a hardware interrupt. For more information on the NMI, see the 8086 Hardware 
Reference Manual, the 80286 Hardware Reference Manual or the 386 m Hardware Reference 
Manual.) 
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2.3 PICTORIAL REPRESENTATION OF SYNTAX 

This chapter uses a schematic device to illustrate command syntax. The schematic consists 
of what looks like an aerial view of a model railroad, with syntactic elements (appearing in 
circles) scattered along the track. To construct a valid command, imagine that a train 
enters the system at the far left, travels from left to right only (backing up is not allowed), 
chooses one branch at each fork, and finally departs at the far right. The command 
generated consists of the syntactic elements it encounters on its journey. The following 
schematic shows two valid sequences: AC and BC. 




W-0940 



These schematics do not show spaces as elements, but you may include one or more spaces 
between the command and parameter. For example, even though the syntax for VR is as 
follows: 



™ — < "sr 
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The following command is valid: 
. . VR xxxx <CR> 

The space between "VR" and "xxxx" is optional. 
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2.4 LEAVING THE MONITOR 



iRMX I Note: The discussion of warm-start and CLI-restart below applies to iRMX II 
only. 



Two features enable you to leave the monitor without resetting your system: warm-start 
and CLI-restart. You will also leave the monitor when your application terminates 
normally. 

The warm-start feature is the process of starting a system without reloading it from 
secondary storage. Warm-start reinitializes the system. It begins executing the application 
system at the same point where the Bootstrap Loader passes control to the system. 

To warm-start an iRMX II system from the iSDM monitor, enter the following command: 

. .g 284:0a <CR> 

If no system code or data segments were corrupted, the system reinitializes. If segment 
corruption has occurred, the application system will not run; you must reboot the system. 

If your system contains a Command Line Interpreter, and running your application 
program causes an exception that breaks to the monitor (for example, a General 
Protection exception), enter the following command to CLI-restart an iRMX II system 
from the iSDM monitor: 

. .g 284:14 <CR> 

These commands causes the system to attempt to delete the job tree of the running task. If 
the running task is part of the application's job (not a subsystem task running for the job) 
control returns to the Command Line Interpreter. Otherwise, you must reboot the system. 
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2.5 COMMAND DIRECTORY 

Command Page 

DISPLAYING iRMX DATA STRUCTURES 

VB--Display DUIB Information 2-6 

VD--Display a Job's Object Directory 2-13 

VF-Display Number of Free Slots 2-16 

VJ-Display Job Hierarchy 2-20 

VK-Display Ready and Sleeping Tasks 2-24 

VO-Display Objects in a Job 2-36 

VR--Display I/O Request/ Result Segment 2-39 

VT~Display iRMX Object 2-48 

RECOGNIZING AND DISPLAYING iRMX SYSTEM CALLS 

VC--Display System Call Information 2-10 

VS--Display Stack and System Call Information 2-43 

VU--Display System Calls in a Task's Stack 2-74 

MULTIBUS® II MESSAGE PASSING COMMANDS 

VMF--Toggle MPC Fail-Safe Timeout 2-26 

VMI--Display Input Message Buffer 2-28 

VMO-Display Output Message Buffer 2-32 

OTHER COMMANDS 

VH-Display Help Information 2-18 
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The VB command displays the DUIB information for the specified physical device. For 
additional information about Device-Unit Information Blocks (DUIBs), refer to Chapter 4 
of the iRMX® Device Drivers User's Guide. 




Physical device 
name 
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Parameter 

Physical device 



The name of the physical device for which you want to view the 
DUIB information (e.g., WMFO). This device must be part of the 
system configuration. 



Description 

The VB command displays the DUIB information for the specified physical device. Figure 
2-1 illustrates the output from the VB command. 



Device name: 


<physical device 


name> 




Functs : 


XX 


DUIB address 


xxxx : xxxx 


Dev$gran 


xxxx 


Max$buffers 


xx 


Dev$size 


xxxxxxxx 


Device 


xx 


Unit 


XX 


Dev$unit 


xxxx 


Device$info$p 


xxxx : xxxx 


Unit$info$p 


xxxx : xxxx 


Update$ timeout 


xxxx 


Num$buffers 


xxxx 


Priority 


XX 


Fixed$update 


XX 


Init$io 


xxxx : xxxx 


Finish$io 


xxxx : xxxx 


Queue$io 


xxxx : xxxx 


Cancel$io 


xxxx : xxxx 


Flags : 


XX 


Valid 




Density 


XXXXXX 


Sides 


xxxxxx 


Size 


X 


Format 


xxxxxxxx 


File driver: 


xxxx 


Named 


xxxx 


Physical 


xxxx 


Stream 


xxxxx 



Figure 2-1. Format of VB Output. 



2-6 



System Debugger 



VB--DISPLAY DUIB INFORMATION 



The fields displayed in Figure 2-1 are as follows: 
Functs 



DUIB address 
Dev$gran 



Max$buffers 

Dev$size 

Device 

Unit 

Dev$unit 

Device$info$p 

Unit$info$p 

Update$timeout 

Num$buffers 

Priority 
Fixed$update 

Init$io 

Finish$io 
Queue$io 



A BYTE used to specify the I/O function validity for this device- 
unit. 

The starting address in memory of the specified DUIB. 

A WORD that specifies the device granularity, in bytes. This 
parameter applies to random access devices, and to some common 
devices, such as tape drives. It specifies the minimum number of 
bytes of information that the device reads or writes in one 
operation. 

The maximum number of buffers that the EIOS can allocate for a 
connection to this device-unit when the connection is opened by a 
call to S$OPEN. 

The number of bytes of information that the device-unit can store. 

The number of the device with which this device-unit is associated. 

The number of this device-unit, which distinguishes this unit from 
other units of the device. 

The device-unit number, which distinguishes this device-unit from 
other device-units in the hardware system. 

A POINTER to a structure that contains additional information 
about the device. The common, random, and terminal device 
drivers require a Device Information Table in a specific format, for 
each device. 

A POINTER to a structure that contains additional information 
about the unit. Random access, common device (such as tape 
drives), and terminal device drivers require this Unit Information 
Table in a specific format. 

The number of system time units that the I/O System must wait 
before writing a partial sector, after processing a write request for a 
disk device. 

The number of buffers of device-granularity size that the I/O 
System allocates. 

The priority of the I/O System service task for the device. 

Indicates whether the fixed update option was selected for this 
device-unit when the application system was configured. 

The address of the Initialize I/O procedure associated with this 
unit. 

The address of the Finish I/O procedure associated with this unit. 

The address of the Queue I/O procedure associated with this unit. 
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Cancel$ io 

Flags 

Valid 

Density 

Sides 

Size 

Format 



File driver: 
Named 
Physical 
Stream 



The address of the Cancel I/O procedure associated with this unit. 

Specifies the characteristics of diskette devices. 

Indicates whether the Flags field is "Valid" or "Not Valid" for this 
device. 

The density of the device. If the flags for this DUIB are invalid, this 
field is marked "N/A". 

The number of media sides that the device can write to. If the flags 
for this DUIB are invalid, this field is marked "N/A". 

The physical size of the device (5 1/4-inch or 8-inch). If the flags for 
this DUIB are invalid, this field is marked "N/A". 

Indicates whether track of a disk is to be formatted as a 
STANDARD diskette (128 bytes/sector) or as a UNIFORM 
diskette (all sectors formatted as specified). This parameter applies 
only to flexible diskettes. Hard disks are always specified as 
UNIFORM. If the flags for this DUIB are invalid, this field is 
marked "N/A". 

A WORD that indicates the BIOS file driver to which this 
connection is attached. 

Indicates whether this device is configured to use the Named file 
driver. 

Indicates whether this device is configured to use the Physical file 
driver. 

Indicates whether this device is configured to use the Stream file 
driver. 
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Error Messages 

Syntax Error 
VB not supported 



DUIB not found 



An error was made when entering the command. The correct syntax 
isVB < physical device >. Any other syntax produces this message. 

VB couldn't find the byte bucket DUIB entry in the BIOS code 
segment. If no DUIB entry for the byte bucket exists, VB is 
unsupported. 

If the BIOS has not been configured into the system, or if the BIOS 
code segment has execute-only attributes, this error message is 
returned. 

VB returns this error message under these conditions: 

1. The DUIB is not configured into the system. 

2. The DUIB entry for the specified device is located before 
the byte bucket DUIB entry. 

3. The user made an error while entering the physical device 
name. 
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The VC command checks to see if a CALL instruction is an iRMX system call. The VC 
command identifies system calls for all iRMX Operating System layers. 



I 




pointer 




T 
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Parameter 

pointer 



The address of the CALL instruction to be checked. This 
parameter can be any valid monitor address (two four-digit 
hexadecimal numbers separated by a colon). 

If you are using the iSDM monitor and you do not supply a pointer 
(or you specify 0), this parameter defaults to the current CS:IP. If 
you specify an IP value (one four-digit hexadecimal number) but not 
a CS value, the System Debugger uses the current CS as the default 
base. 



Description 

If the CALL instruction is an iRMX system call, the VC command displays information 
about the CALL instruction as shown in Figure 2-2. 



gate #NNNN 

(sub system) system call 



Figure 2-2. Format of VC Output 
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The fields in Figure 2-2 are as follows: 



gate #NNNN 

(subsystem) 
system call 



The gate number associated with the iRMX system call at the 
address specified in the command. 

The iRMX Operating System layer corresponding to the system call. 

The name of the iRMX system call. 



NOTE 

The System Debugger uses the gate number to determine whether the CALL 
instruction represents a system call. Since the System Debugger does not 
disassemble the code, but rather examines a byte value at a particular offset 
from the CALL instruction, in rare cases a non-system call can be displayed as 
an iRMX system call. However, the System Debugger does recognize and 
display all iRMX system calls. 



Error Messages 

Syntax Error 

Not a system CALL 

Not a CALL instruction 



An error was made in entering the command. 

The parameter specified points to a CALL instruction 
that is not an iRMX system call. 

The CS:IP specified does not point to any type of call 
instruction. 



Examples 

Suppose you disassembled the following code using the iSDM monitor's Display Memory 
(DX) command: 



18A0:006D 50 


PUSH 


AX 




18A0:006E E8AD1E 


CALL 


A - 1F1E 


;$+7856 


18A0:0071 E8DD03 


CALL 


A = 0451 


;$+992 


18A0:0074 B80000 


MOV 


AX,0 




18A0:0077 50 


PUSH 


AX 




18A0:0078 8D060600 


LEA 


AX, WORD PRT 006 




18A0.-007C IE 


PUSH 


DS 




18A0:007D 50 


PUSH 


AX 




18A0:007E E8411E 


CALL 


A = 1EC2 


;$+7748 


18A0:0081 A30000 


MOV 


WORD PTR 0000H,AX 
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If you use the VC command on the CALL instruction at address 18A0:006E by entering 
the following command: 

. .VC 18A0:006E <CR> 
The System Debugger displays the following information: 



gate #0468 

(Nucleus) set exception handler 



Gate number 0468 corresponds to an RQ$SET$EXCEPTION$HANDLER system call, a 
Nucleus call. 

Now, suppose you want to see if the CALL instruction at 18A0:0071 is a system call. Enter 
the following command: 

. .VC 18A0:0071 <CR> 
The System Debugger responds with the following: 



Not a system CALL 



Finally, if you use the VC command on the instruction at 18A0:0074, the System Debugger 
responds with the following: 



Not a CALL instruction 
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The VD command displays a job's object directory. 
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Parameter 

job token 



The token for the job having the object directory you want 
displayed. To obtain the job token, use the VJ command. 



Description 

If you specified a valid job token, the System Debugger displays the job's object directory, 
as shown in Figure 2-3. 



Directory 


size: xxxx 


Entries 


used: xxxx 


namel 
name 2 


tokenl 

tasks waiting 


token2 . 


. . tokeni 


namej 
namek 


tokenj 
tokenk 






namen 


tokenn 







Figure 2-3. Format of VD Output 
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Figure 2-3 shows these fields: 



Directory size 

Entries used 
namel...namen 

tokenl...tokenn 
tasks waiting 



The maximum number of entries this job can have in its object 
directory. 

The number of entries in the directory. 

The names under which objects are catalogued. These names were 
assigned at the time the objects were catalogued with 
RQ$CATALOG$OBJECT. 



Tokens for the catalogued objects. 

Signifies that one or more tasks have done an 
RQ$LOOKUP$OBJECT on an object not catalogued. The tokens 
following this field identify the tasks still waiting for the object to be 
catalogued. 

For more information on object directories, see the iRMX® II Nucleus User's Guide or the 
iRMX® I Nucleus User's Guide. 



Error Messages 

Syntax Error 
TOKEN is not a Job 



No parameter was specified for the command, or an 
error was made in entering the command. 



A valid token was entered that is not a job token. 

*** INVALID TOKEN *** The value entered for the token is not a valid token (as 

defined in "Checking Validity of Tokens" earlier in this 
chapter). 



Example 

Suppose you want to look at the object directory of job "2280". Enter the following 
command: 

. .VD 2280 <CR> 
The System Debugger responds with 



Directory size: 000A Entries used: 0003 



$ 

R?I0USER 

RQGLOBAL 



2228 
2200 
2280 
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The symbols "$", "R7IOUSER", and "RQGLOBAL" are the names of objects the system 
creates; their respective tokens are 2228, 2200, and 2280. There are no waiting tasks or 
invalid entries. 
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The VF command displays the number of free Global Descriptor Table slots available to 
the user. 
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Parameters 

The VF command has no parameters. 
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Description 

The VF command displays the number of free Global Descriptor Table (GDT) slots 
available to the user, in the format shown in Figure 2-4. 



Number of free slots = xxxxxxxx 



Figure 2-4. Format of VF Output 



Error Messages 

Syntax Error An error was made in entering the command. 
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The VH command displays and briefly describes the System Debugger commands (iRMX 
II displays 15 commands; iRMX I displays 12 commands.) 
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Parameters 

This command has no parameters. 

Description 

The VH command lists all the System Debugger commands, along with their parameters 
and descriptions. 

Error Message 

Syntax Error An error was made in entering the command. 

Example 

If you enter the following command: 

. . VH <CR> 
The System Debugger responds as shown in Figure 2-5. 
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iRMX II SYSTEM DEBUGGER, Vx.y 
Copyright <year> Intel Corporation 



vb <Dev Name> 

vc [<POINTER>] 

vd <Job TOKEN> 

vf 

vh 

vj [<Job TOKEN>] 

vk 

vo <Job TOKEN> 

vr <Seg TOKEN> 

vs [<count>] 

vt <TOKEN> 

vu <task TOKEN> 

vmi [<msg #>] [ , ] 

vmo [<msg //>] [ , ] 

vmf 



Displays DUIB for physical device. 

Display system call. 

Display job's object directory. 

Displays number of free slots available to user, 

Display help information. 

Display job hierarchy from specified level. 

Display ready and sleeping tasks. 

Display list of objects for specified job. 

Display I/O Request/Result Segment. 

Display stack and system call information. 

Display iRMX object. 

Unwind task stack, displaying system calls. 

Display the MPC input message buffer. 

Display the MPC output message buffer. 

Toggle the MPC fail-safe timeout. 



Figure 2-5. Format of VH Output 



< > Angle brackets surround required variable fields. 

[< >] Square and angle brackets surround optional fields. 



iRMX I Note: The last three lines in the display above apply only to iRMX II. They do 
not appear in the iRMX I display. 



NOTE 

The system uses default values if you specify zero (0) for any of the optional 
parameters in Figure 2-5. Using zero for required parameters causes the 
system to display the following message: 



Syntax Error 
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The VJ command displays the portion of the job hierarchy that descends from the level you 
specify. 
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Parameter 

job token 



The token of the job for which you want to display descendant jobs. 

If you do not specify a job token, or you specify zero (0), VJ displays 
the root job and its descendant jobs. 

If the job has more than 44 generations of job descendants, the 
System Debugger stops the display at the 44th descendant level, 
displays an error message, and prompts for another command. 



Description 

The VJ command displays the token of the specified job and the tokens of all its 
descendant jobs. It also displays the tokens of jobs (and their descendants) at the same 
level as the specified job. The tokens for descendant jobs are indented three spaces to 
show their job's position in the hierarchy. Figure 2-6 shows the format of the job hierarchy 
display. 



iRMX® <I/II> Job Tree 



token-i 

token2 

tokerio 

token^ 
tokenc 
tokeng 
tokens 



Root Job 

Human Interface 

Command Line Interpreter 

Application 

EIOS 

iRMX-NET (if present) 

BIOS 



Figure 2-6. Format of VJ Output 
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The fields in Figure 2-6 are 

token j The token you specified as job token (recall that the root job token 

is the default). 

token^-.tokeny The tokens for the descendant jobs of token i. 

In Figure 2-6, the Human Interface, EIOS, and BIOS Jobs are indented three spaces to 
signify that they are children of the Root Job. Similarly, the Command Line Interpreter 
Job is the child of the Human Interface Job (as are all first level user jobs), and the 
Application Job is the child of the Command Line Interpreter Job. 

Error Messages 

Syntax Error An error was made in entering the command. 

TOKEN is not a Job A valid token was entered that is not a job token. 

*** INVALID TOKEN *** The value entered for the token is not a valid token (as 

defined in "Checking Validity of Tokens" earlier in this 
chapter). 

SDB job nest limit The specified job (or the default job) has more than 44 

exceeded generations of job descendants. 

Examples 

If you want to examine the hierarchy of the root job, enter the following command: 

. . VJ <CR> 
Suppose the System Debugger responds with the following job tree: 



iRMX® <I/II> Job Tree 

0258 

0F38 

1670 

2460 
0E88 
0E00 
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Figure 2-7 shows this job tree: 



Root Job 
(0258) 



Human Interface EIOS 

(0F38) (0E88) 



BIOS 
(0E00) 



Command Line Interpreter 
(1670) 



Application 
(2460) 
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Figure 2-7. iRMX® Job Tree 



If you want to display the descendant jobs of "0E88", enter the following command: 
. .VJ 0E88 <CR> 
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The System Debugger displays the following: 



iRMX® Job Tree 

0E88 
0E00 
0F38 

1670 

2460 



Note that the tokens for all jobs at the same level as the specified token (0E00 and 0F38), 
and their descendants (1670 and 2460), are also displayed. 
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The VK command displays the tokens for tasks in the ready and sleeping states. 
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Parameters 

This command has no parameters. 

Description 

The VK command displays the tokens for tasks that are ready and asleep, in the format 
shown in Figure 2-8. 



Ready tasks : 
Sleeping tasks: 



xxxx xxxx . 



xxxx xxxx 



Figure 2-8. Format of VK Output 



The fields in Figure 2-8 show the following: 

Ready tasks The tokens for all tasks in the ready state. The first token in this list 

represents the running task. 

Sleeping tasks The tokens for all tasks in the sleeping state. 



Error Messages 

Syntax Error 

Ready tasks: Can't locate 

Sleeping tasks: Can't locate 



An error was made in entering the command. 

The system is corrupted. 

The most common reason for this type of error is 
not initializing the Nucleus. To recover from this 
error, reinitialize the system. 
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Example 

To display a list of all the ready and sleeping tasks in your system, enter the following 
command: 

. .VK <CR> 
The System Debugger responds with the following: 



Ready tasks : 


2F00 
















Sleeping tasks: 


26F0 


2588 


26B8 


2200 


21B0 


2090 


25E8 


2050 




2020 


1FF8 


2698 


2238 


2118 


2668 


2638 


2768 




20D0 


0300 
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VMF-TOGGLE M PC FAIL-SAFE TIMEOUT 



iRMX I Note: This command applies only to MULTIBUS® II systems (iRMX II). 



The VMF command enables or disables the Message Passing Coprocessor (MPC) fail-safe 
timeout feature. This command can be used only in a MULTIBUS II system. 




VMF 
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Parameters 

This command has no parameters. 

Description 

The VMF command enables and disables the fail-safe timer on the Message Passing 
Coprocessor (MPC). Multiple invocations of this command will alternately enable and 
disable the fail-safe timer. 

The MPC fail-safe timer limits how long (about two seconds on an iSBC® 386/116 or 
iSBC® 386/120 board) the MPC will wait between sending a buffer request message and 
receiving a buffer grant or buffer reject message. This hardware timeout ensures that the 
MPC will not wait forever when trying to communicate with another host that has failed 
during the buffer negotiation phase. When debugging a message-passing application, it is 
useful to disable the fail-safe timer so either host may be stopped for indefinite periods 
while debugging commands are executing. When you are finished debugging, you must use 
the VMF command to re-enable the fail-safe timer before re-starting your application. 



NOTE 

The MPC fail-safe timer must be re-enabled before re-starting an application 
after debugging. Otherwise, your application may not function properly. 
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NOTE 

To use the VMF command, you must specify at least one trace message on the 
Nucleus Communication Service screen in the ICU. For details on the Number 
of Trace Messages configuration parameter, see the iRMX® II Interactive 
Configuration Utility Reference Manual. 

Error Messages 

Syntax Error An error was made in entering the command. 

Example 

If you enter the following command: 

. .VMF <CR> 
one of these two messages will be displayed: 



MPC Failsafe Timer Is Enabled 


or 


MPC Failsafe Timer Is Disabled 
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iRMX I Note: This command applies only to MULTIBUS II systems (iRMX II). 



The VMI command displays the contents of the messages received from the Message 
Passing Coprocessor (MPC). This command can be used only in a MULTIBUS II system. 
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Parameters 

msg# 



The number of the message to display. If this parameter is omitted, 
the most recent message is displayed. If the comma (,) parameter is 
also entered, this field specifies the first message to display. 

Specifies that you want to view more than one message in the input 
message buffer. When you specify this parameter, SDB displays the 
first message and then displays a special prompt, a dash (-), at the 
end of the line. If you enter another comma, SDB displays the next 
most recent message in the input message buffer. The debugger 
then issues another special prompt (-) and waits for you to either 
enter another comma or to end the command. You can end the 
VMI command by entering a carriage return in response to the 
special prompt (-). 



Description 

The VMI command displays the field values associated with the input messages received 
from the MPC input message buffer. These fields are used by the iRMX Nucleus 
Communication Service, an implementation of the MULTIBUS II Transport Protocol. 
This section briefly describes each field. For a more detailed description of the fields, refer 
to the MULTIBUS® II Transport Protocol Specification and Designer's Guide. 
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NOTE 

The VMI command displays the most recent messages in the input message 
buffer. The number of messages you can display depends on how many trace 
messages you allocate on the Nucleus Communication Service screen in the 
ICU. For example, if you specify five trace messages, you will be able to display 
the five most recent messages. To use the VMI command, you must specify at 
least one trace message. For details on the Number of Trace Messages 
configuration parameter, see the iRMX® II Interactive Configuration Utility 
Reference Manual. 

The format of the VMI output depends on the type of message. Figure 2-8.3 shows the 
fields that may be displayed. 



## message type req_id: xx src_hid: xx dest_hid: xx len: xxxxxx 

trans control trans_id: xx src_pid: xxxx dest_pid: xxxx xmit_c: xx 
len: xxxxxxxx 



Figure 2-8a. Format of VMI Output 



The first 
fields on 

## 
message 

req_id 
src_hid 
dest_hid 
len 



line of the display contains hardware-level information about the message. The 
this line are: 



type 



The message number. 

The type of message (hardware-level protocol). Possible values are 
Unsolicited, Broadcast, Buf Request, and Unknown Type. 

Request Id. This ID defines a particular message transfer. 

Host ID of the sender of the message. 

Host ID of the receiver of the message. 

The length (in bytes) of the requested transfer. This field is only 
displayed for buffer request messages. For other types of messages, 
this field is blank. 
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The second line of the display contains software protocol information about the message. 
If the protocol of the message is not the data trasport protocol, the following is displayed: 



Unknown Protocol 



If the protocol being used is the data transport protocol, the following fields are displayed: 

trans control A representation of the transaction control field of the message. If 

the message is not a request or response message, this field is blank; 
otherwise, this field indicates the type of request or response 
message. Possible values for this field are: 

Resp/EOT Response message, end-of-transaction 

(EOT). Indicates that this is the last 
fragment of a reply. 



trans id 



Resp/Not EOT 

Resp/Cancel 

Resp/ Reserved 
Req/Frag Off 

Req/Frag On 

Req/Send Frag 

Req/Next Frag 



Response message, not end-of- 
transaction (EOT). Indicates that more 
fragments of the reply will follow. 

Response message with cancellation. 
Indicates that the sender of the reply 
(the server) is cancelling the transaction. 

Reserved type. Undefined at present. 

Request message with fragmentation 
disallowed. The request cannot be sent 
in fragments. 

Request message with fragmentation 
allowed. The request can be sent in 
fragments, if necessary. 

Request message, send next fragment. 
The next fragment of a fragmented 
transfer can be sent. 

Request message containing the next 
fragment of a fragmented transfer. 



Transaction ID. A number that uniquely identifies a transaction. 
This field will be zero for transactionless messages (unsolicited or 
solicited messages with no reply expected). 
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The port ID of the sender of the message. 

The port ID of the receiver of the message. 

Transmission control. The high-order two bits of this field indicate 
the protection level of the message. Level is the most privileged 
level and level 3 is the least. 



If the trans control field indicates that the message is a Req/Send Frag message, the third 
line of the display contains the following field: 

len The length (in bytes) of the requested fragment. 

Otherwise, the third line shows the user data portion of the control message in 
hexadecimal words. If the message type or software protocol are unknown, the entire 
message is displayed in hexadecimal words, beginning on the third line. 

NOTE 

You cannot use the VMI command to view the contents of short-circuit 
messages. 



Error Messages 

Syntax Error 

Message Information Is 
Not Available 



An error was made in entering the command. 

The system is not a MULTIBUS II system or no trace 
messages were specified during configuration. The number 
of trace messages is specified on the Nucleus 
Communication Service screen in the ICU. For details, 
refer to the iRMX® II Interactive Configuration Utility 
Reference Manual. 
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iRMX I Note: This command applies only to MULTIBUS II systems (iRMX II). 



The VMO command displays the contents of the output messages sent by the Message 
Passing Coprocessor (MPC). This command can be used only in a MULTIBUS II system. 
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Parameters 

msg# 



The number of the message to display. If this parameter is omitted, 
the most recent message is displayed. If the comma (,) parameter is 
also entered, this field specifies the first message to display. 

Specifies that you want to view more than one message in the 
output message buffer. When you specify this parameter, SDB 
displays the first message and then displays a special prompt, a dash 
(-), at the end of the line. If you enter another comma, SDB 
displays the next most recent message in the output message buffer. 
The debugger then issues another special prompt (-) and waits for 
you to either enter another comma or to end the command. You 
can end the VMO command by entering a carriage return in 
response to the special prompt (-). 



Description 

The VMO command displays the field values associated with the output messages sent by 
the MPC. These fields are used by the iRMX Nucleus Communication Service, an 
implementation of the MULTIBUS II Transport Protocol. This section briefly describes 
each field. For a more detailed description of the fields, refer to the MULTIBUS® II 
Transport Protocol Specification and Designer's Guide. 
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NOTE 

The VMO command displays the most recent messages in the output message 
buffer. The number of messages you can display depends on how many trace 
messages you allocate on the Nucleus Communication Service screen in the 
ICU. For example, if you specify five trace messages, you will be able to display 
the five most recent messages. To use the VMO command, you must specify at 
least one trace message. For details on the Number of Trace Messages 
configuration parameter, see the iRMX® II Interactive Configuration Utility 
Reference Manual. 

The format of the VMO output depends on the type of message. Figure 2-8.2 shows the 
fields that may be displayed. 



//# message type req_id: xx src_hid: xx dest_hid: xx YYYYYYY 

trans control trans_id: xx src_pid: xxxx dest_pid: xxxx xmit_c: xx 
len: xxxxxxxx 



Figure 2-8b. Format of VMO Output 



The first line of the display contains hardware-level information about the message. The 
fields on this line are: 



## 
message type 

req_id 
src_hid 
dest hid 



The message number. 

The type of message (hardware-level protocol). Possible values are 
Unsolicited, Broadcast, Buf Request, Buf Grant, Buf Reject, and 
Unknown Type. 

Request Id. This ID defines a particular message transfer. 

Host ID of the sender of the message. 

Host ID of the receiver of the message. 
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YYYYYYY This part of the first line is only displayed for buffer request, buffer 

grant, and buffer reject messages. It can consist of one of two fields. 
For buffer request messages, the following field is displayed: 

len The length (in bytes) of the requested 
transfer. 

For buffer grant and buffer reject messages, this field is displayed. 

l_id Liaison ID. This ID binds a buffer 
grant or buffer reject message to a 
buffer request message. 

The second line of the display contains software protocol information about the message. 
If the protocol of the message is not the data transport protocol, the following is displayed: 

Unknown Protocol 

If the protocol being used is the data transport protocol, the following fields are displayed: 



trans control 



A representation of the transaction control field of the message. If 
the message is not a request or response message, this field is blank; 
otherwise, this field indicates the type of request or response 
message. Possible values for this field are: 



Resp/EOT 

Resp/Not EOT 

Resp/Cancel 

Resp/ Reserved 
Req/Frag Off 

Req/Frag On 



Response message, end-of-transaction 
(EOT). Indicates that this is the last 
fragment of a reply. 

Response message, not end-of- 
transaction (EOT). Indicates that more 
fragments of the reply will follow. 

Response message with cancellation. 
Indicates that the sender of the reply 
(the server) is cancelling the transaction. 

Reserved type. Undefined at present. 

Request message with fragmentation 
disallowed. The request can not be 
sent in fragments. 

Request message with fragmentation 
allowed. The request can be sent in 
fragments, if necessary. 
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Req/Send Frag 



Request message, send next fragment. 
The next fragment of a fragmented 
transfer can be sent. 



trans_id 

src_pid 
dest_pid 
xmit c 



Req/Next Frag Request message containing the next 
fragment of a fragmented transfer. 

Transaction ID. A number that uniquely identifies a transaction. 
This field will be zero for transactionless messages (unsolicited or 
solicited messages with no reply expected). 

The port ID of the sender of the message. 

The port ID of the receiver of the message. 

Transmission control. The high-order two bits of this field indicate 
the protection level of the message. Level is the most privileged 
level and level 3 is the least. 



If the trans control field indicates that the message is a Req/Send Frag message, the third 
line of the display contains the following field: 

len The length (in bytes) of the requested fragment. 

Otherwise, the third line shows the user data portion of the message in hexadecimal words. 
If the message type or software protocol are unknown, the entire message is displayed in 
hexadecimal words, beginning on the third line. 

NOTE 

You cannot use the VMI command to view the contents of short-circuit 
messages. 



Error Messages 

Syntax Error 

Message Information Is 
Not Available 



An error was made in entering the command. 

The system is not a MULTIBUS II system or no trace 
messages were specified during configuration. The number 
of trace messages is specified on the Nucleus 
Communication Service screen in the ICU. For details, 
refer to the iRMX® II Interactive Configuration Utility 
Reference Manual. 
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The VO command displays the tokens for the objects in the specified job. 
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Parameter 

job token 

Description 



The token of the job for which you want to display objects. 



The VO command lists the tokens for a job's: 
child jobs 
tasks 

mailboxes 
semaphores 
regions 
segments 
extensions 
composites 
buffer pools 

It uses the format shown in Figure 2-9. 



Child Jobs: 


xxxx 


xxxx 


xxxx 


Tasks : 


xxxx 


xxxx 


xxxx 


Mailboxes : 


xxxx 


xxxx 


xxxx 


Semaphores : 


xxxx 


xxxx 


xxxx 


Regions : 


xxxx 


xxxx 


xxxx 


Segments : 


xxxx 


xxxx 


xxxx 


Extensions : 


xxxx 


xxxx 


xxxx 


Composites : 


xxxx 


xxxx 


xxxx 


Buffer Pools: 


xxxx 


xxxx 


xxxx 



Figure 2-9. Format of VO Output 
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The fields in Figure 2- 

Child Jobs 

Tasks 

Mailboxes 



Semaphores 

Regions 

Segments 

Extensions 

Composites 

Buffer Pools 



9 are as follows: 

The tokens for the specified job's offspring jobs. 

The tokens for the tasks in the specified job. 

The tokens for the mailboxes in the job. An "o" following a mailbox 
token means that one or more objects are queued at the mailbox. A 
"t" following a mailbox token means that one or more tasks are 
queued at the mailbox. 

The tokens for the semaphores in the specified job. A T following 
a semaphore token means that one or more tasks are queued at the 
semaphore. 

The tokens for the regions in the specified job. A "b" (busy) 
following a region token means that a task has access to information 
guarded by the region. 

The tokens for the segments in the specified job. 

The tokens for the extensions in the specified job. 

The tokens for the composites in the specified job. A "s" following a 
composite signifies a port with a signal waiting. An "m" signifies a 
port with a message waiting. A "t" signifies a port with a task 
waiting. 

The tokens for the buffer pools in the specified job. 



Error Messages 

Syntax Error 

TOKEN is not a Job 

*** INVALID TOKEN ** : 



No parameter was specified for the command or an error 
was made in entering the command. 

A valid token was entered; however, it is not a job token. 

The value entered for the token is not a valid token (as 
defined in "Checking Validity of Tokens" earlier in this 
chapter). 



Example 

If you want to look at the objects in the job having the token "1670", enter the following 
command: 

. .VO 1670 <CR> 
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The System Debugger responds with the following: 



Child jobs: 


2460 












Tasks : 


1688 


1778 


17B8 


1940 


1950 


2FF8 


Mailboxes : 


1720 


1728 


1738 t 


1740 t 


1760 t 


1768 t 


Semaphores : 


17A0 


17A8 t 










Regions : 














Segments : 


16D8 


1750 


1958 


1960 


2FE8 


2FC8 


Extensions : 














Composites : 


1690 


16F0 


1710 


1828 


1848 


1980 


Buffer pools : 















This display shows the tokens for the job, as described earlier. It also tells you that tasks 
are waiting at four mailboxes and one semaphore. 
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The VR command displays information about the iRMX Basic I/O System I/O 
Request/ Result Segment (IORS) that corresponds to the segment token you enter. 




segment 
token 
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Parameter 

Segment token 



The token for a segment containing the IORS you want to display. 
If this segment is not an IORS, the VR command returns invalid 
information. To obtain a list of the segment tokens in a job, use the 
VO command. 



Description 

The VR command displays the names and values for the fields of a specific IORS. The 
contents of the IORS reflect the most recent I/O operation in which this IORS was used. 
The System Debugger ensures the specified segment is between 45 and 65 bytes long. It 
cannot tell whether the segment contains a valid IORS, so you must ensure that it does. If 
the parameter is a valid segment token for a segment containing an IORS, the System 
Debugger displays information about the IORS as shown in Figure 2-10. For more 
information on I/O Request/ Result Segments, see the iRMX® Basic I/O System User's 
Guide. 

For more detailed information about the IORS contents, see the iRMX® Device Drivers 
User's Guide. 
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I/O Request Result 


Segment 






Status 


xxxx 


Unit status 


xxxx 


Device 


xxxx 


Unit 


XX 


Function 


xxxxxxx 


Sub function 


xxxxxxx 


Count 


xxxx 


Actual 


xxxx 


Device location 


xxxxxxxx 


Buffer pointer 


xxxx : xxxx 


Resp mailbox 


xxxx 


Aux pointer 


xxxx : xxxx 


Link forward 


xxxx : xxxx 


Link backward 


xxxx : xxxx 


Done 


xxxxx 


Cancel ID 


xxxx 


Connection token 


xxxx 







Figure 2-10. Format of VR Output 



The fields in Figure 2-10 are as follows: 



Status 
Unit status 



Device 

Unit 

Function 



The condition code for the I/O operation. 

Additional status information. The contents of this field are 
significant only when the Status field is set to the E$IO condition 
(002BH). If the Status field is not set to E$IO, the Unit Status field 
displays "N/A". 

The number of the device for which this I/O request is intended. 

The number of the unit for which this I/O request is intended. 

The operation done by the Basic I/O System. The possible 
functions are 



Function 


Svstem Call 


Read 


RQ$A$READ 


Write 


RQ$A$WRITE 


Seek 


RQ$A$SEEK 


Special 


RQ$A$SPECIAL 


Att Dev 


RQ$A$PHYSICAL$ATTACH$DEVICE 


Det Dev 


RQ$A$PHYSICAL$DETACH$DEVICE 


Open 


RQ$A$OPEN 


Close 


RQ$A$CLOSE 



If the Function field contains an invalid value, the System Debugger 
displays the actual value in this field, followed by a space and two 
question marks. 
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Subfunction 



An added specification of the function that applies only when the 
Function field contains "Special" from the BIOS RQ$A$SPECIAL 
system call. Possible subfunctions and their descriptions are 



Count 
Actual 
Device location 

Buffer pointer 

Resp mailbox 

Aux pointer 

Link forward 

Link backward 



Subfunction 

For/Que 
Satisfy 
Notify 
Device char 
Get Term Attr 
Set Term Attr 
Signal 
Rewind 

Read File Mark 
Write File Mark 
Retention Tape 
Set Font 
Set Bad Info 
Get Bad Info 
Get term status 
Cancel I/O 
Resume I/O 



Description 

Format or Query 

Stream file satisfy function 

Notify function 

Device characteristics 

Get terminal attributes 

Set terminal attributes 

Signal function 

Rewind tape 

Read file mark on tape 

Write file mark on tape 

Take up slack on tape 

Set character font 

Set bad track/sector information 

Get bad track/sector information 

Get terminal status 

Cancel terminal I/O 

Resume terminal I/O 



If the Function field doesn't contain "Special," then the Subfunction 
field contains "N/A." If the Subfunction field contains an invalid 
value, the System Debugger displays the value of the field followed 
by a space and two question marks. 

The number of bytes of data called for in the I/O request. 

The number of bytes of data transferred in response to the request. 

The eight-digit hexadecimal address of the byte or logical block 
where the I/O operation began on the specified device. 

The address of the buffer the Basic I/O System read from, or wrote 
to, in response to the request. 

A token for the response mailbox to which the device sent the IORS 
after the operation. 

The pointer to the location of auxiliary data, if any. This field is 
significant only when the Function field contains "Special." 

The address of the next IORS in the queue where the IORS waited 
to be processed. 

The address of the previous IORS in the queue where the IORS 
waited to be processed. 
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Done 



Cancel ID 



Connection token 



This field is always present but applies only to IORSs for I/O 
operations on random-access devices. When applicable, it indicates 
whether the I/O operation has been completed. The possible values 
are TRUE (OFFH) and FALSE (00H). 

A word used by device drivers to identify I/O requests that need to 
be canceled. A value of zero (0) indicates a request that cannot be 
canceled. 

The token for the file connection used to issue the request for the 
I/O operation. 



Error Messages 

Syntax Error No parameter was specified for the command or an error 

was made in entering the command. 

TOKEN is not a SEGMENT The token entered is valid but not a segment token. 

*** INVALID TOKEN *** The value entered for the token is not a valid token (as 

defined in "Checking Validity of Tokens" earlier in this 
chapter). 

SEGMENT wrong size - The specified segment is not between 45 and 65 bytes long, 

not an IORS so it is not an I/O Request/ Result Segment. 
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The VS command identifies system calls (as does the VC command) and displays the stack. 
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Parameter 

count 



A decimal or hexadecimal value that specifies the number of words 
from the stack to be included in the display. A suffix of T, as in 16T, 
means decimal. No suffix or a suffix of H indicates hexadecimal. 

If you do not specify a count, or you specify a count of zero (0), the 
number of words in the display depends on the number of 
parameters for the system call at the CS:IP. When CS:IP is not 
pointing to a system call, the entire contents of the stack are 
displayed. 



Description 

The VS command identifies iRMX system calls for all iRMX subsystems (as does the VC 
command). It interprets the system call parameters on the stack. If the stack does not 
contain a system call, the VS command displays either the number of stack elements you 
specify or all the stack contents, whichever is least. If a parameter is a string, the System 
Debugger displays the string. For additional system call information, see the appropriate 
iRMX Volume 3 system call manual. 

The VS command interprets the CALL instruction at the current CS:IP. If you want to 
interpret a CALL instruction at a different CS:IP value, you must move the CS:IP to that 
value. To move the CS:IP using the iSDM monitor, use the GO (G) command or the 
EXAMINE/MODIFY REGISTER command (X with CS or IP specified as the 8086, 
80286 or 386™ register). 

If the instruction is not a CALL instruction, VS displays the contents of the words on the 
stack and no message. If the instruction is a CALL but not a system call (for example, a 
PL/M call to a procedure), VS displays the stack contents. It also displays a message 
telling you that the CALL was not a system call. 

The VS command uses current values of the SS:SP (Stack SegmentrStack Pointer) registers 
to display the current stack values. If the instruction is an iRMX system call, VS displays 
the system call and the stack information as shown in Figure 2-11. 
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gate #NNNN 














xxxx : xxxx xxxx 


xxxx xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx : xxxx xxxx 


xxxx xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


( subsys tern) sys tem 


call 

| parameters | 













Figure 2-11. Format of VS Output 



The fields in Figure 2-11 are as follows: 



xxxxrxxxx 
xxxx 

parameters 



The contents of the SS:SP (stack memory addresses). 

Values (tokens) now on the stack. The number of stack values 
varies, depending on the number of parameters in the system call. 

The names of the stack values. The parameters correspond to the 
stack values directly above them. The maximum number of 
displayed parameters is 24. 



The three remaining fields in Figure 2-11 are the same as those in the VC command: 
gate #NNNN The gate number associated with the system call. (iRMX II only) . 

(subsystem) The iRMX Operating System layer that the system call is part of. 

system call The name of the iRMX system call. 



Error Messages 

Syntax Error 



An error was made in entering the command. 



Not a system CALL The CS:IP is pointing to a CALL instruction that is not an iRMX 

system call. 



Unknown entry 
code 



This message indicates that one of two infrequent events has 
occurred. One is that the System Debugger has mistaken an 
operand belonging to some instruction in the object code for the 
FAR CALL instruction. The other event is that a software link 
from user code into iRMX code has been corrupted. To recover 
from system corruption, reboot the system. 
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Examples 

Suppose you determine that the SS:SP is 1906:07CA (using the iSDM Monitor's X 
command, for example) then use the VS command by entering the following command: 

..vs <CR> 
The System Debugger responds with the following: 



gate #0360 














1906:07CA 0B08 1980 


1EA8 


1980 


1980 


0000 


0B00 


1908 


1906:07DA 19A0 0B20 


0580 


1EA8 


1EA0 


1EE8 


0000 


0000 


(Nucleus) delete mailbox 














| . . excep$p . . | 


.mbox. 













The parameter names identify the stack values directly above them. That is, the "excep$p" 
parameter name signifies that the first two words represent a pointer (1980:0B08) to the 
exception code. Similarly, the "mbox" parameter signifies that the third word (1EA8) is the 
token for the mailbox being deleted. 

Now, suppose that you move the SS:SP to 2906:07D0. If you invoke the VS command by 
entering the following command: 

. . vs <CR> 

The System Debugger displays the following stack and a message informing you that the 
instruction is a CALL instruction but not an iRMX system call: 



2906:07D0 2980 


2980 


0000 


0600 


2908 


29A0 


0020 


1580 


2906:07E0 27C8 


27C8 


25C8 


25C8 


25C8 


25C8 


25C8 


25C8 


Not a system CALL 

















When an iRMX system call is executed, its parameters are pushed onto the current stack, 
and then a CALL instruction is issued with the appropriate stack address. If the call has 
more parameters than will fit on one line, the System Debugger automatically displays 
multiple lines of stack values. It shows corresponding multiple lines of parameter 
descriptions directly below them. 
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For example, suppose you use the VS command as follows: 
. . vs <CR> 



gate #0310 












27CC:0F9A 0158 20C8 


0000 


20C8 20C8 


0000 


0600 


17C8 


27CC-.0FAA 20E8 0028 


0000 


000O 20C8 


00E0 


2FF8 


2FF8 


27CC:0FBA 2608 1A58 


1AF8 


2608 0000 


0000 


0000 


0000 


(Nucleus) create job 












| . . . excep$p ... | 


.t$flgs. 


| stksze| . . sp. 


| . .ss. . 


| ..ds.. 


|..ip-.| 


| ..cs.. | ..pri. | 


•j$flgs. 


| .exp$info$p. 


|maxpri 


| maxtsk 


|maxobj | 


| poolmx | poolran | 


.param. . 


jdirsizj 









This display indicates that the CALL instruction is a Nucleus RQ$CREATE$JOB system 
call with 18 parameters. The names of these parameters are shown between the vertical 
bars ( | ). The words on the stack correspond to the parameters directly below them. 

The following display shows that the CALL instruction is a Basic I/O System (BIOS) 
RQ$A$ATTACH$FILE system call with five parameters. The "subpath$p" parameter 
points to a string seven characters long: the word "example." 

. . VS <CR> 



gate #0500 










27CC:0F4E 0F88 17C8 


25F8 


0000 2600 


29A0 0000 


2600 


27CC:0F5E 2608 1C10 


2600 


1320 26D0 


0F78 0DF8 


2FF8 


(BIOS) attach file 










| . . . . excep$p . . . 


. mbox . 


. . subpath$p . . 


. prefix | .user| 




subpath--> 07 'example' 











The following display indicates that the CALL instruction at CS:IP is an Extended I/O 
System RQ$S$RENAME$FILE system call with three parameters. Two of the parameters 
have strings: the "new$path$p" parameter points to a string four characters long ("XY70"); 
the "path$p" parameter points to another string four characters long ("temp"). 



VS <CR> 
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gate #06E8 










27CC:0F98 0148 20C8 


0858 20E8 


06A0 20E8 


0000 


0600 


27CC:0FA8 17C8 20E8 


0028 1320 


0000 20C8 


0008 


2600 


(EIOS) rename file 










| . .excep$p. . 


. .new$path$p. 


|...path$p... 






new path--> 04'XY70' 










path--> 04 'temp' 











NOTE 

If a string is more than 50 characters long, the System Debugger displays only 
the first 50 characters. If the pointer is pointing to a nonreadable segment, the 
System Debugger does not display the string. 
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The VT command displays information about the iRMX object associated with the token 
you enter. 
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Parameter 

token 

Description 



The token of the object for which you want to display information. 



The VT command determines the type of iRMX object represented by the token and 
displays information about that object. Both the information and the format in which the 
System Debugger displays the information depend on the type of object. 

The following sections are divided into display groups illustrating the display format for 
these iRMX objects: 



Jobs 

Tasks 

Mailboxes 

Semaphores 

Regions 



Segments 

Extensions 

Composite objects (six types) 

Buffer Pools (iRMX II only) 



Error Messages 

Syntax Error 



No parameter was specified for the command or an 
error was made in entering the command. 



*** INVALID TOKEN *** The value entered for the token is not a valid token (as 

defined in "Checking Validity of Tokens" earlier in this 
chapter). 
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Job Display 

If the parameter you specify is a valid job token, the System Debugger displays information 
about the job having that token, as Figure 2-12 shows. 



Object type = 1 Job 

Current tasks xxxx 
Current objects xxxx 
Directory size xxxx 
Except handler xxxx: xxxx 
Pool min xxxxx 
Borrowed xxxxx 



Max tasks xxxx 

Max objects xxxx 

Entries used xxxx 

Except mode xx 

Pool max xxxxx 



Max priority xx 

Parameter obj xxxx 

Job flags xxxx 

Parent job xxxx 

Initial size xxxxx 



Byte range 


Number chunks 


Largest chunk 


Total memory 


22-44H 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


44-84H 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


84-200H 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


200H-1K 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


1K-2K 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


2K-4K 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


4K-8K 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


8K-32K 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 


+32K 


xxxxxxxx 


xxxxxxxx 


xxxxxxxx 



Figure 2-12. Format of VT Output: Job Display 



The fields in Figure 2-12 (from left to right) are as follows: 



Current tasks 

Max tasks 

Max priority 

Current objects 
Max objects 



The number of tasks currently existing in the job. If the Max tasks is 
not OFFFFH (no limit), the number of Current tasks is equal to the 
Current tasks of this job plus all its children Max tasks. 

The maximum number of tasks that can exist in the job 
simultaneously. This value was set when the job was created. 

The maximum (numerically lowest) priority allowed for any one task 
in the job. This value was set when the job was created. 

The number of objects currently existing in the job. 

The maximum number of objects that can exist in the job 
simultaneously. This value was set when the job was created. 
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Parameter obj 
Directory size 

Entries used 
Job flags 

Except handler 
Except mode 

Parent job 
Pool min 

Pool max 

Initial size 
Borrowed 

Free Space 



The token for the object that the parent job passed to this job. This 
value was set when the job was created. 

The maximum number of entries the job can have in its object 
directory. This value was specified by the first parameter when the 
job was created with the Nucleus RQ$CREATE$JOB system call or 
the RQE$CREATE$JOB system call (iRMXIIonlv) . 

The number of objects now catalogued in the job's object directory. 

The job flags parameter specified when the job was created. It 
contains information the Nucleus needs to create and maintain the 
job. 

The start address of the job's exception handler. This address was 
set when the job was created. 

The value that indicates when control is to be passed to the new 
job's exception handler. This value was set when the job was 
created. 

The token for the specified job's parent. 

The minimum size (in 16-byte paragraphs) of the job's memory 
pool. This value was set when the job was created. 

The maximum size (in 16-byte paragraphs) of the job's memory 
pool. This value was set when the job was created. 

The initial size (in 16-byte paragraphs) of the job's memory pool. 

The current amount (in 16-byte paragraphs) of memory that the job 
has borrowed from its ancestor (s). 

All free memory in a job's pool is accounted for, via several double- 
linked lists. Each list contains a range of chunk sizes. A chunk is a 
piece of contiguous memory. Column one of the free space table 
shows the size ranges for the list. Column two shows the number of 
chunks on each list. Column three displays the largest chunk on 
each list. Column four shows the total amount of memory on each 
list. 
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Task Display 

The System Debugger displays information about tasks in two different ways. Figure 2-13 
shows the display for non-interrupt tasks, and Figure 2-14 shows the display for interrupt 
tasks. 



Object type =■ 2 


Task 










Static pri 


XX 


Dynamic pri 


XX 


Task state 


xxxxxxxxx 


Suspend depth 


XX 


Delay req 


xxxx 


Last exchange 


xxxx 


Except handler 


xxxx : xxxx 


Except mode 


XX 


Task flags 


XX 


Containing job 


xxxx 


Interrupt task 


no 


K- saved SS:SP 


xxxx : xxxx 



Figure 2-13. Format of VT Output: Non-interrupt Task 



Object type = 2 


Task 










Static pri 


XX 


Dynamic pri 


XX 


Task state 


xxxxxxxxx 


Suspend depth 


XX 


Delay req 


xxxx 


Last exchange 


xxxx 


Except handler 


xxxx : xxxx 


Except mode 


XX 


Task flags 


XX 


Containing job 


xxxx 


Interrupt task 


yes 


Int level 


XX 


Master mask 


XX 


Slave mask 


XX 


Pending int 


XX 


Max interrupts 


XX 


K- saved SS:SP 


xxxx: 


xxxx 





Figure 2-14. Format of VT Output: Interrupt Task 



The fields in Figures 2-13 and 2-14 (from left to right) are as follows: 

Static pri The maximum priority value of the task. This value was set by the 

max$priority parameter when the task's containing job was created 
with RQ$CREATE$JOB or RQE$CREATE$JOB. (iRMXIIonh;) 
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Dynamic pri 



Task state 



Suspend depth 
Delay req 
Last exchange 



A temporary priority that the Nucleus sometimes assigns to the task 
to improve system performance. For example, if a higher priority 
task wants control of a region that belongs to a currently executing 
lower priority task, the Nucleus assigns the lower priority task a 
priority equal to that of the higher priority task. This increasing of a 
task's priority improves the total system performance here. 

The state of the task. The twelve possible states, as they are 
displayed, are 



State 



Description 



ready 


task is ready for 




execution 


asleep 


task is asleep 


susp 


task is suspended 


aslp/susp 


task is both asleep and 




suspended 


deleted 


task is being deleted 


on exch Q 


task is waiting at an 




exchange 


aslp/exch 


task is asleep waiting 




at an exchange 


sl/xc/susp 


task is asleep and 




suspended waiting at 




an exchange 


on port Q 


task is queued at a port 


aslp/port 


task is asleep waiting at 




a port 


on trans Q 


task is queued at a port 




on transaction queue 


aslp/trans 


task is asleep and 




queued at port on 




transaction queue 



If this field contains an invalid value, the System Debugger displays 
the value followed by a space and two question marks. 

The number of RQ$SUSPEND$TASK system calls that have been 
applied to this task without corresponding RQ$RESUME$TASK 
system calls. 

The number of sleep units the task requested when it last specified a 
delay at a mailbox or semaphore, or when it last called RQ$SLEEP. 
If the task has not done any of these, this field contains zeros. 

The token for the mailbox, region, or semaphore at which the task 
most recently began to wait. 
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Except handler 



Except mode 



Task flags 

Containing job 
Interrupt task 



K-saved SS:SP 
Int level 
Master mask 



Slave mask 



Pending int 



The start address of the job's default exception handler. This value 
was set either when the task was created with 
RQ$CREATE$TASK, RQ$CREATE$JOB, RQE$ CREATES JOB, 
or later with RQ$SET$EXCEPTION$HANDLER. 

The value that indicates the exceptional conditions under which 
control is to be passed to the new task's exception handler. This 
value was set either when the task was created with 
RQ$CREATE$TASK, RQ$CREATE$JOB, RQE$CREATE$JOB, 
or later with RQ$SET$EXCEPTION$HANDLER. 

The task flags parameter used when the task was created with 
RQ$CREATE$TASK. It contains information the Nucleus needs 
to create and maintain the job's initial task. 

The token of the job that this task belongs to. 

Indicates whether this task is an interrupt task. "No" signifies that 
the task is not an interrupt task. Here, only the K-saved field 
follows in the display. (See Figure 2-13.) 

"Yes" signifies that the task is an interrupt task. In this case, 
additional fields appear in the display. (See Figure 2-14.) 

The contents of the SS:SP registers when the task last left the ready 
state. 

The level that the interrupt task services. This level was set when 
this task called RQ$SET$INTERRUPT. 

The value associated with the interrupt mask for the master 
interrupt controller. This value represents the master interrupt 
levels disabled by the interrupt level that the task services. 

For example, if the task services master interrupt level 68H, then 
master levels 6 and 7 are disabled, so the master mask field is 
11000000B ( = 0C0H). For more information about interrupt levels, 
see the iRMX® II Nucleus User's Guide or the iRMX® I Nucleus 
User's Guide. 

The value associated with the interrupt mask for a slave interrupt 
controller. This value represents the slave interrupt levels disabled 
by the level that the task services. 

For example, if the task services slave interrupt level 62H, then slave 
levels 2 through 7 are disabled, so the slave level field is 11111100B 
( = 0FCH). For more information about interrupt levels, see the 
iRMX® II Nucleus User's Guide or the iRMX® I Nucleus User's Guide. 

The number of RQ$SIGNAL$INTERRUPT calls pending for the 
Int level. 
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Max interrupts 



The maximum number of RQ$SIGNAL$INTERRUPT calls that 
can be pending for the Int level. 



Mailbox Display 

The System Debugger displays information about mailboxes in three different ways: 

• Figure 2-15 shows the display when nothing is queued at the mailbox. 

• Figure 2-16 shows the display when tasks are queued at the mailbox. 

• Figure 2-17 shows the display when objects are queued at the mailbox. 

• Figure 2-18 shows the display when data messages are queued at the mailbox. 



Object type = 3 Mailbox 

Mailbox type xxxxxx 

Queue discipline xxxx 

Containing job xxxx 



Task queue head xxxx 

Object queue head 0000 
Object cache depth xx 



Figure 2-15. Format of VT Output: Mailbox with No Queue 



Object type = 3 Mailbox 



Mailbox type 


xxxxxx 


Queue discipline 


xxxx 


Containing job 


xxxx 


Task queue 


zzzz : 



xxxx 



Task queue head zzzz 
Object queue head 0000 
Object cache depth xx 



Figure 2-16. Format of VT Output: Mailbox with Task Queue 
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Object type = 3 Mailbox 

Mailbox type xxxxxx 
Queue discipline xxxx 
Containing job xxxx 



Task queue head xxxx 
Object queue head zzzz 
Object cache depth xx 



Object cache queue zzzz xxxx 
Object overflow queue xxxx xxxx 

Figure 2-17. Format of VT Output: Mailbox with Object Queue 



Object type = 3 Mailbox 

Mailbox type xxxxxx 
Queue discipline xxxx 
Containing job xxxx 

Data message queue xxxx: xxxx 

xxxx : xxxx 



Task queue head zzzz 
Data queue head xxxx: xxxx 



xxxx : xxxx 
xxxx : xxxx 



xxxx : xxxx 



Figure 2-18. Format of VT Output: Mailbox with Data Message Queue 



The fields in Figures 2-15, 2-16, 2-17, and 2-18 are as follows: 

Mailbox type The type of mailbox: object or data. Mailbox type is either 

Object or Data. The mailbox type is defined when the 
mailbox is created. 

The token for the task at the head of the queue. If the task 
queue for this mailbox is empty, this field contains the 
mailbox token. 

The token for the object at the head of the queue. If the 
object queue for this mailbox is empty, this field contains 
"0000". If the mailbox type is "Data", this field contains 

"N/A". 



Task queue head 



Object queue head 
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Queue discipline 



Object cache depth 



Containing job 
Task queue 

Object cache queue 

Object overflow queue 

Data queue head 
Data message queue 



Indicates how tasks are queued at the mailbox. Tasks are 
queued as "FIFO" (first-in-first-out) or by "PRI" (priority), 
depending on how the mailbox was defined when it was 
created with RQ$CREATE$MAILBOX. If the System 
Debugger can't interpret this field, it displays the actual 
value followed by a space and two question marks. 

The size of the high-performance cache portion of the 
object queue associated with the mailbox. This size was 
specified when the mailbox was created with 
RQ$CREATE$MAILBOX. If the mailbox type is "Data", 
this field contains "N/A". 

The token for the job that contains this mailbox. 

A list of tokens for the tasks queued at the mailbox in the 
order they are queued. If there are no tasks in the task 
queue, this field is not displayed. 

A list of tokens for the objects queued in the object cache 
queue, in the order they are queued. If there are no 
objects in the object cache queue or the mailbox type is 
Data, this field is not displayed. 

A list of tokens for the objects queued in the object 
overflow queue, in the order they are queued. If there are 
no objects in the object overflow queue or the mailbox type 
is Data, this field is not displayed. 

The pointer for the first data message at the head of the 
message queue. 

Pointers for the data messages residing at the mailbox. 
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Semaphore Display 

The System Debugger displays information about semaphores in two ways. The first 
display appears when no tasks are queued at the semaphore (Figure 2-19). The second 
appears when tasks are queued at the semaphore (Figure 2-20). 



Object type = 4 Semaphore 

Task queue head xxxx Queue discipline xxxx 

Current value xxxx Maximum value xxxx 

Containing job xxxx 



Figure 2-19. Format of VT Output: Semaphore with No Queue 



Object type = 4 Semaphore 

Task queue head xxxx Queue discipline xxxx 

Current value xxxx Maximum value xxxx 

Containing job xxxx 

Task queue xxxx xxxx 

Figure 2-20. Format of VT Output: Semaphore with Task Queue 



The fields in Figures 2-19 and 2-20 are as follows: 

Task queue head The token for the task at the head of the queue. If the task queue is 

empty, this field contains zeros. 

Queue discipline Indicates how tasks are queued at the semaphore. Tasks are 

queued as "FIFO" (first-in-first-out) or by "PRI" (priority), 
depending on how the semaphore was specified when it was created 
with RQ$CREATE$SEMAPHORE. 

Current value The number of units currently held by the semaphore. 
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The maximum number of units the semaphore can hold. This 
number was specified when the semaphore was created with 
RQ$CREATE$SEMAPHORE. 

The token for the job that the semaphore belongs to. 

A list of tokens for the tasks queued at the semaphore, in the order 
they are queued. If no tasks are queued, this list does not appear. 



Maximum value 

Containing job 
Task queue 

Region Display 

If the parameter you supply is a valid token for a region, the System Debugger displays 
information about the associated region as shown in Figures 2-21 and 2-22. 



Object type = 5 Region 



Entered task 
Containing job 



xxxx Queue discipline 

xxxx 



xxxx 



Figure 2-21. Format of VT Output: Region with No Queue 



Object type = 5 Region 



Entered task 
Containing job 

Task queue 



xxxx 
xxxx 



xxxx xxxx 



Queue discipline 



xxxx 



Figure 2-22. Format of VT Output: Region with Task Queue 
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The fields in Figures 2-21 and 2-22 are as follows: 



Entered task 
Queue discipline 



Containing job 
Task queue 



The token for the task currently accessing information guarded by 
the region. 

Indicates how tasks are queued at the region. Tasks are queued as 
"FIFO" (first-in-first-out) or by "PRI" (priority), depending on how 
the region was specified when it was created with 
RQ$CREATE$REGION. 

The token for the job that the region belongs to. 

Tokens for the tasks waiting to gain access to data guarded by the 
region. This line is displayed only if a task is already in the region 
and another task is waiting. 



Segment Display 

If the parameter that you supply is a valid token for a segment, the System Debugger 
displays information about the associated segment as shown in Figure 2-23. 



Object type = 6 Segment 
Segment size xxxx 



Containing job 



xxxx 



Figure 2-23. Format of VT Output: Segment 



The fields in Figure 2-23 are as follows: 



Segment size 



Containing job 



The number of bytes in this segment. The size of the segment was 
specified when the segment was created with 
RQ$CREATE$SEGMENT. 

The token for the job that the segment belongs to. 
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Extension Object Display 

If the parameter that you supply is a valid token for an extension, the System Debugger 
displays information about the associated extension as shown in Figure 2-24. 



Object type = 7 Extension 

Extension type xxxx Deletion mailbox xxxx 

Containing job xxxx 



Figure 2-24. Format of VT Output: Extension Object 



The fields in Figure 2-24 are as follows: 

Extension type The type code associated with composite objects licensed by this 

extension. This code was specified when the extension type was 
created with RQ$CREATE$EXTENSION. See the iRMX® II 
Nucleus User's Guide or the iRMX® I Nucleus User's Guide for more 
information about extension types. 

Deletion mailbox The token for the deletion mailbox associated with this extension. 

This mailbox was specified when the extension type was created with 
RQ$CREATE$EXTENSION. 

Containing job The token for the job that the extension belongs to. 

Composite Object Display 

The VT command displays the following kinds of composite information: 

All composites except those defined in the Basic I/O System (BIOS) and the port 
connection 

BIOS user objects 

BIOS physical file connections 

BIOS stream file connections 

BIOS named file connections 

BIOS remote file connections 

Port connection (iRMX II only) 

Figure 2-25 shows the format for the display of non-BIOS objects. 
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Object type = 8 Composite 

Extension type xxxx Extension obj xxxx Deletion mbox xxxx 

Containing job xxxx Num of entries xxxx 

Component list xxxx xxxx xxxx xxxx 

Figure 2-25. Format of VT Output: Composite Object Other Than BIOS 



The fields in Figure 2-25 are as follows: 

Extension type The code for the extension type of the extension object used to 

create this composite. This code was specified when the extension 
object was created with RQ$CREATE$EXTENSION. 

Extension obj The token for the extension object used to create this composite 

object. 

Deletion mbox The token for the mailbox to which this composite goes when the 

composite is to be deleted. This mailbox was specified when the 
extension was created with RQ$ CREATES EXTENSION. 

Containing job The token for the job that the composite object belongs to. 

Num of entries The number of component entries in the composite object. 

Component list The list of tokens for the components of the composite. 

Figure 2-26 shows the format for the Basic I/O System user object display. 



Object type = 8 Composite 

Extension type xxxx Extension obj xxxx Deletion mbox xxxx 

Containing job xxxx Num of entries xxxx 

BIOS USER OBJECT: 
User segment xxxx Number of IDs xxxx 

User ID list xxxx xxxx 



Figure 2-26. Format of VT Output: BIOS User Object Composite 
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Figure 2-26 uses the composite display described in Figure 2-25 as a base and appends the 
following fields: 

User segment The token for the segment containing the user IDs for the user 

object. 

Number of IDs The number of user IDs associated with the user object. 

User ID list List of the user IDs associated with the user object. 

Figure 2-27 shows the format for a (file) connection to a physical file. 



Object type = 8 


Composite 










Extension type 


xxxx 


Extension obj 


xxxx 


Deletion mbox 


xxxx 


Containing job 


xxxx 


Num of entries 


xxxx 






T$CONNECTION OBJECT: 










File driver 


Physical 


Conn flags 


XX 


Access 


xxxx 


Open mode 


xxxxxx 


Open share 


XXXXXXX 


File pointer 


xxxxxxxx 


IORS cache 


xxxx 


File node 


xxxx 


Device desc 


xxxx 


Dynamic DUIB 


xxxxx 


DUIB pointer 


xxxx : xxxx 


Num of conn 


xxxx 


Num of readers 


xxxx 


Num of writers 


xxxx 


File share 


XXXXXXX 


File drivers 


xxxx 


Device gran 


xxxx 


Device size 


XXXXXXXX 


Device functs 


xxxx 


Num dev conn 


xxxx 


Device name 


XXXXXXXXXX 



Figure 2-27. Format of VT Output: BIOS Physical File Connection 



Figure 2-27 uses the composite display described in Figure 2-25 as a base and appends the 
following fields: 



File driver 



The BIOS file driver to which this connection is attached. The four 
possible values are Physical, Stream, Named, and Remote. If this 
field contains an invalid value, the System Debugger displays the 
value followed by a space and two question marks. 
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Conn flags 



The flags for the connection. To determine how the flag is set, 
convert the hexadecimal value to binary. The following description 
shows the connection state when a bit (0 is the rightmost bit) is set 
tol: 



Bit 



Condition 




1 

2 
3 
4 

5-7 



The connection is being detached 

The connection is active and can be 

opened 

This is a device connection 

Reserved 

The connection was forcibly 

detached 

Reserved 



Access 



The access rights for this connection. This display uses a single 
character to represent each access right. If the connection has the 
access right, the character appears. If the connection does not have 
an access right, a hyphen (-) appears in the character position. The 
access rights and the characters that represent them are 



Directory files: 



Delete 
List 
Add 
Change 



Data Files 



D R 



U 



Update 
Append 
Read 
Delete 



Open mode 



The mode established when this connection was opened. The 
possible modes are 



Open Mode 


Description 


Closed 


Connection is closed 


Read 


Connection is open for 




reading 


Write 


Connection is open for 




writing 


R/W 


Connection is open for 




reading and writing 
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Open share 



File pointer 
IORS cache 

File node 

Device desc 

Dynamic DUIB 

DUIB pointer 

Num of conn 
Num of readers 
Num of writers 



If this field contains an invalid value, the System Debugger displays 
the value, followed by a space and two question marks. If this value 
is Read, Write, or R/W, this value was specified when the 
connection was opened. 

The sharing status established for this connection when it was 
opened. The sharing status for a connection is a subset of the 
sharing status of the file (see the File share field). The possible 
modes are 



Share Mode 


Description 


Private 


File cannot be shared 


Readers 


File can be shared with 




readers 


Writers 


File can be shared with writers 


ALL 


File can be shared with all 




users 





Connection is not open 



If this field contains an invalid value, the System Debugger displays 
the value, followed by a space and two question marks. This 
probably indicates that the connection data structure has been 
corrupted. 

The current location of the file pointer for this connection. 

The token for the segment at the head of the BIOS list of used 
IORSs. These IORSs are being saved for the RQ$WAIT$IO system 
call to use again. This list is empty if zeros appear in this field. 

The token for a segment that the operating system uses to maintain 
information about the connection. The information in this segment 
appears in the next two fields. 

The token for the segment that contains the device descriptor. The 
device descriptor is used by the operating system to maintain 
information about connections to a device. 

Indicates whether a Device Unit Information Block (DUIB) was 
created dynamically when the device associated with this connection 
was attached. 

The address of the DUIB for the device unit containing the file. See 
the iRMX® Device Drivers User's Guide for more information about 
DUIBs. 

The number of connections to the file. 

The number of connections now open for reading. 

The number of connections now open for writing. 



2-64 



System Debugger 



VT--DISPLAY iRMX® OBJECT 



File share 



File drivers 



The share mode of the file. This parameter defines how other 
connections to the file can be opened. The share mode of a file is a 
superset of the sharing status of each of the connections to the file 
(see the Open share field description). The possible modes are 

Share Mode Description 

Private File cannot be shared 

Readers File can be shared with readers 

Writers File can be shared with writers 

All File can be shared with all users 

If this field contains an invalid value, the System Debugger displays 
the value, followed by a space and two question marks. This 
probably means that the internal data structure for the file or the 
fnode for the file has been corrupted. See the iRMX® Basic I/O 
System Users Guide for more information about sharing modes for 
files and connections. 

The file drivers that connect the file. If the file can be connected to 
a given file driver, then the bit in the display is set to 1. Bit is the 
rightmost bit. 



Device gran 



Device size 



Bit 


1 
2 
3 
4 



Driver 

Physical file 
Stream file 
Reserved 
Named file 
Remote file 



The granularity (in bytes) of the device. This is the minimum 
number of bytes that can be written to or read from the device in a 
single (physical) I/O operation. 

The capacity (in bytes) of the device. 
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Device functs 



Num dev conn 
Device name 



Describes the functions supported by the device where this file is 
stored. Each bit in the low-order byte of the field corresponds to 
one of the possible device functions. If that bit is set to 1, then the 
corresponding function is supported by the device. 



Bit 



Function 






F$READ 


1 


F$WRITE 


2 


F$SEEK 


3 


F$SPECIAL 


4 


F$ATTACH$DEV 


5 


F$DETACH$DEV 


6 


F$OPEN 


7 


F$CLOSE 



The number of connections to the device. 

The 14-character (or fewer) name of the device where this file is 
stored. 



Figure 2-28 shows the format for a (file) connection to a stream file. 



Object type = 8 


Composite 








Extension type 


xxxx 


Extension obj 


xxxx 


Deletion mbox 


xxxx 


Containing job 


xxxx 


Num of entries 


xxxx 






T$CONNECTION OBJECT 


: 








File driver 


Stream 


Conn flags 


XX 


Access 


xxxx 


Open mode 


xxxxxx 


Open share 


XXXXXX 


File pointer 


xxxxxxxx 


IORS cache 


xxxx 


File node 


xxxx 


Device desc 


xxxx 


Dynamic DUIB 


xxxxx 


DUIB pointer 


xxxx : xxxx 


Num of conn 


xxxx 


Num of readers 


xxxx 


Num of writers 


xxxx 


File share 


xxxxxxx 


File drivers 


xxxx 


Device gran 


xxxx 


Device size 


xxxx 


Device functs 


xxxx 


Num dev conn 


xxxx 


Device name 


Stream 


Req queued 


xxxx 


Queued conn 


xxxx 


Open conn 


xxxx 



Figure 2-28. Format of VT Output: BIOS Stream File Connection 



Figure 2-28 uses the physical display described in Figure 2-27 as a base and appends the 
following fields: 

Req queued The number of requests now queued at the stream file. 
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Queued conn The number of connections now queued at the stream file. 

Open conn The number of connections to the stream file now open. 

Figure 2-29 shows the format for a file connection to a named file. 



Object type = 8 Composite 



Extension type xxxx 
Containing job xxxx 



Extension obj xxxx 
Num of entries xxxx 



Deletion mbox xxxx 



T$CONNECTION OBJECT: 



File driver 


Named 


Conn flags 


xx 


Access 


xxxx 


Open mode 


xxxxxx 


Open share 


xxxxxx 


File pointer 


xxxxxxxx 


IORS cache 


xxxx 


File node 


xxxx 


Device desc 


xxxx 


Dynamic DUIB 


xxxxx 


DUIB pointer 


xxxx : xxxx 


Num of conn 


xxxx 


Num of readers 


xxxx 


Num of writers 


xxxx 


File share 


xxxx 


File drivers 


xxxx 


Device gran 


xxxx 


Device size 


xxxxxxxx 


Device functs 


xxxx 


Num dev conn 


xxxx 


Device name 


xxxx 


Num of buffers 


xxxx 


Fixed update 


xxxx 


Update timeout 


xxxx 


Fnode number 


xxxx 


File type 


xxxxxxxxx 


Fnode flags 


xxxx 


Owner 


xxxxx 


File/Vol gran 


xxxx 


Fnode PTR(s) 


xxxx : xxxx 


Total blocks 


xxxxxxxx 


Total size 


xxxxxxxx 


This size 


xxxxxxxx 


Volume gran 


xxxx 


Volume size 


xxxxxxxx 


Volume name 


xxxxxx 



Figure 2-29. Format of VT Output: BIOS Named File Connection 



Figure 2-29 uses the physical display described in Figure 2-27 as a base and appends the 
following fields: 



Num of buffers 
Fixed update 
Update timeout 
Fnode number 



The number of buffers allocated for blocking and unblocking I/O 
requests involving the device. A value of zero (0) indicates that the 
device is not a random-access device. 

TRUE or FALSE indicates whether the device uses the fixed 
update timeout feature. For more information about update 
timeout, see the iRMX® Basic I/O System User's Guide. 

The length of the time for the update timeout feature, measured in 
Nucleus time units. For more information about fixed updating, see 
the iRMX® Basic I/O System User's Guide. 

The fnode number of this file. For more information about fnodes, 
see the iRMX® Disk Verification Utility Reference Manual. 
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File type 



The type of named file. The possible values are 



File type 

DIR 

DATA 

SPACEMAP 

FNODEMAP 
BADBLOCKMAP 



Description 

Directory file 

Data file 

Volume free space map 

file 

Free fnodes map file 

Bad blocks file 



Fnode flags 



Owner 

File/Vol gran 
Fnode PTR(s) 

Total blocks 

Total size 
This size 
Volume gran 
Volume size 
Volume name 



If this field contains an invalid value, the System Debugger displays 
the value, followed by a space and two question marks. 

A word containing flag bits. If a bit is set to 1, the following 
description applies. Otherwise, the description does not apply. (Bit 
is the rightmost bit.) 



Bit 



1 

2 

3-4 

5 



7-15 



Description 

This fnode is allocated 

The file is a long file 

Primary fnode 

Reserved 

This file has been 

modified 

This file is marked for 

deletion 

Reserved 



The ID of the owner of the file. If this field has a value of OFFFFH, 
then the field is displayed as "WORLD". See the iRMX® Basic I/O 
System User's Guide for more information about file ownership. 

The granularity of the file (in volume granularity units). 

The addresses of the fnode pointers. See the iRMX® Disk 
Verification Utility Reference Manual for more information about 
fnode pointers. 

The total number of volume blocks used for the file at present; this 
includes indirect blocks. See the iRMX® Disk Verification Utility 
Reference Manual for more information about blocks. 

The total size (in bytes) of the file; this includes actual data only. 

The total number of bytes allocated to the file for data. 

The granularity (in bytes) of the volume. 

The size (in bytes) of the volume. 

The name of the volume. 
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Figure 2-30 shows the format for a file connection to a remote file. 



Object type = 8 Composite 



Extension type xxxx 
Containing job xxxx 

T$CONNECTION OBJECT: 



Extension obj xxxx 
Num of entries xxxx 



Deletion mbox xxxx 



File driver 


Remote 


Conn flags 


XX 


Access 


xxxx 


Open mode 


xxxxxx 


Open share 


XXXXXX 


File pointer 


xxxxxxxx 


IORS cache 


xxxx 


File node 


xxxx 


Device desc 


xxxx 


Dynamic DUIB 


xxxxx 


DUIB pointer 


xxxx : xxxx 


Num of conn 


xxxx 


Num of readers 


xxxx 


Num of writers 


xxxx 


File share 


xxxx 


File drivers 


xxxx 


Device gran 


xxxx 


Device size 


xxxxxxxx 


Device functs 


xxxx 


Num dev conn 


xxxx 


Device name 


xxxx 



Figure 2-30. Format of VT Output: BIOS Remote File Connection 



The fields in Figure 2-30 are the same as the fields in Figure 2-27, except for the File driver 
field, which is "Remote" rather than "Physical." 

Figure 2-31 shows the display format for a port having signal protocol type. 



Object type = 8 Composite 

Extension type xxxx Extension obj xxxx Deletion mbox xxxx 
Containing job xxxx Num of entries xxxx 

T$P0RT OBJECT: 
Protocol type Signal Queue discipline xxxx Signal count xxxx 
source id xxxx 

Task queue xxxx xxxx 



Figure 2-31. Format of VT Output: Signal Protocol Port 
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Figure 2-31 uses the composite display described in Figure 2-23 as a base and appends the 
following fields: 

Protocol type The message protocol. This value is "Signal" to indicate signal 

service The type is determined when the port is created through 
RQ$CREATE$PORT. 



Queue discipline 



Signal count 
Source id 



Task queue 



Indicates how tasks are queued at the port. Tasks are queued as 
"FIFO" (first-in-first-out) or by "PRI" (priority), depending on how 
the port was specified when it was created with 
RQ$CREATE$PORT. If this field is uninterpretable, the actual 
BYTE value followed by a space and two question marks appears. 

The number of signals now waiting to be received at the port. 

The board (agent) identification number for which this port was 
created to send messages to or receive messages from. This 
identification number matches the slot number of the remote board. 
The number is established through the "message$id" field when the 
port is created using the utility RQ$CREATE$PORT. 

The tokens for the list of tasks (if any) queued at the port. 



Figure 2-32 shows the display format for a port having data transport protocol type. 



Object type = 8 


Composite 










Extension type 




xxxx 




Extension obj 


xxxx 


Deletion mbox 


xxxx 


Containing job 




xxxx 




Num of entries 


xxxx 






T$PORT OBJECT: 














Protocol type 




Data 


T 


Queue discipline 


xxxx 


Buffer pool 


xxxx 


Fragmentation 




xxx 




Max Port Transctns 


xxxx 


Sink port 


xxxx 


Destination msg 


id 


xxxx 




Destination port id 


xxxx 


Source port id 


xxxx 


Transaction id 




xxxx 




Task token 


xxxx 






Transaction id 




xxxx 




Message pointer 


xxxx: 


xxxx 




Message queue 




xxxx: 


xxxx xxxx : xxxx 









Figure 2-32. Format of VT Output: Data Transport Protocol Port 
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Object type = 8 Composite 








Extension type xxxx 


Extension obj 


xxxx 


Deletion mbox 


Containing job xxxx 


Num of entries 


xxxx 





T$PORT OBJECT: 

Protocol type Data T Queue discipline xxxx 

Fragmentation xxx Max Port Transctns xxxx 

Destination msg id xxxx Destination port id xxxx 

Transaction id xxxx Task token xxxx 
Transaction id xxxx Message pointer xxxx: xxxx 



xxxx 



Buffer pool xxxx 
Sink port xxxx 
Source port id xxxx 



Task queue 



xxxx xxxx 



Figure 2-33. Format of VT Output: Data Transport Protocol Port 



Figures 2-32 and 2-33 use the composite display described in Figure 2-23 as a base and 
append the following fields: 



Protocol type 
Queue discipline 

Buffer pool 
Fragmentation 

Max Port Transctns 
Sink port 



The message protocol. This value is "Data T" to indicate Data 
Transport service The type is determined when the port is created 
through RQ$CREATE$PORT. 

Indicates how tasks are queued at the port. Tasks are queued as 
"FIFO" (first-in-first-out) or by "PRI" (priority), depending on how 
the port was specified when it was created with 
RQ$CREATE$PORT. 

The token of the attached buffer pool (if any). The utility 
RQ$ATTACH$BUFFER$POOL attaches a buffer pool to a port. 

The fragmentation protocol. This value is either "Yes" if the port 
can handle message fragmentation, or "No" if the port does not 
handle message fragmentation. Port fragmentation protocol is 
defined through the utility RQ$CREATE$PORT. 

The maximum number of simultaneous outstanding transactions for 
the port. This limitation is defined when the port is created using 
RQ$CREATE$PORT. 

The token of the sink port (if any) associated with the port. Sink 
ports are connected to ports through the RQ$ATTACH$PORT 
utility. 
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Destination msg id 
Destination port id 
Source port id 

Transaction id 
Task token 

Message pointer 

Message queue 



The host$id portion of the socket identifying the remote port that 
this port is connected. This value is established through the 
RQ$CONNECT utility. 

The port$id portion of the socket identifying the remote port that 
this port is connected. This value is established through the 
RQ$CONNECT utility. 

The board (agent) identification number for which this port was 
created to send messages to or receive messages from. The number 
is established through the "port$id" field when the port is created 
using the utility RQ$CREATE$PORT. 

Outstanding transaction identification numbers at this port. 

The token(s) of the task or tasks with outstanding transactions at 
this port. 

The pointer of the message(s) with outstanding transactions at this 
port. 

The list of pointers representing the messages queued at this port. 
This field appears only if the port has queued messages. 



NOTE 

Besides the display forms shown in Figures 2-32 and 2-33, the VT output for a 
Data Transport protocol port can appear with the following combinations of 
fields: 

• Transaction information with no Message Queue or Task Queue 
information 

• Message Queue information with no Transaction or Task Queue 
information 

• Task Queue information with no Transaction or Message Queue 
information 

• No Transaction, Message Queue, or Task Queue information 
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Buffer Pool Display 

If the parameter that you supply is a valid token for a buffer pool, the System Debugger 
displays information about the buffer pool as shown in Figure 2-34. 



Object type = 10 Buffer pool 

Max Buffers xxxx Total buffer count xxxx Total size count xxxx 

Containing job xxxx Data Chaining xxx 



Buffer pool contents 

Buffer size xxxx 
Buffer size xxxx 



Buffer count xxxx 

Buffer count xxxx 



Figure 2-34. Format of VT Output: Buffer Pool 



Figure 2-34 display fields are defined as follows 
Max buffers 



Total buffer count 

Total size count 

Containing job 
Data Chaining 

Buffer size 
Buffer count 



The total number of buffers allowed in this buffer pool. This 
maximum value is determined when the buffer pool is created using 
RQ$CREATE$BUFFER$POOL. 

The number of buffers now in the buffer pool. This number is 
equivalent to the number of buffers created in the pool using 
RQ$CREATE$SEGMENT. 

The number of different buffer sizes in the buffer pool. The 
maximum number of different buffer sizes is eight. 

The token for the job that created this buffer pool. 

YES or NO indicates whether this buffer pool supports data 
chaining. 

The available buffer sizes for this buffer pool. These sizes are 
determined when the individual buffers are created through 
RQ$CREATE$SEGMENT. 

The number of buffers that are of the buffer size displayed in the 
field directly to the left. 
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The VU command displays (unwinds) the iRMX system calls in the stack of the task having 
the token you enter. 




W-0954 



Parameter 

token The token for the task having the stack to be searched for system 

calls. 

Description 

The VU command accepts a token for a task and then searches the task's stack for iRMX 
system calls, starting at the top of the stack. For each system call it finds in the stack, it 
displays 

• The return address for the call. This is the address of the next instruction to be 
executed for the task after the system call has finished running. 

• The VS display with two lines of stack values (or more if required for parameters of the 
system call). They are shown as if the CALL instruction for the system call were in the 
CS:IP register and the displayed stack values were at the top of the stack. 

This command requires the task stack to be inside an iRMX segment. 

The VU command uses internal iRMX data structures to get some of its information. The 
data structures are updated immediately after the system call at the top of the task's stack 
runs to completion. Since the monitor interrupt might come after the system call is 
completed, but before the data structures are updated, some of the information the VU 
command uses may be obsolete. Therefore, the first system call the VU command displays 
may not be valid. 

Figure 2-35 illustrates the format of one system call display by the VU command. System 
calls can be nested, with one calling another, so some invocations of the VU command 
produce multiple displays of the type shown in the figure. 
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If the stack of the indicated task has no system calls, the VU command displays the 
following message: 



No system calls on stack 



gate #NNNN 
















Return cs : ip 


- yyyy:yyyy 














xxxx : xxxx 


xxxx xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx : xxxx 


xxxx xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


(subsystem) 


system call 















parameters 



Figure 2-35. Format of VU Output 



The fields in Figure 2-34 are as follows: 



gate #NNNN 

Return cs:ip 

xxxx:xxxx 

xxxx 

(subsystem) 

system call 

parameters 



The gate number associated with the system call. 

The return address for the system call of this display (yyyy:yyyy). 

The address of the stack portion devoted to this call. 

Values now on the stack. 

The iRMX Operating System layer containing the system call. 

The name of the iRMX system call. 

The parameter names associated with the stack values. The 
parameters correspond to the stack values directly above them. If 
one of the parameters is a string, it displays the string contents 
below the parameters. 



System Debugger 



2-75 



VU-DISPLAY SYSTEM CALLS IN A TASK'S STACK 



Error Messages 

Syntax Error An error was made in entering the command. 

* * * INVALID TASK TOKEN * * * The value entered for the token is not a valid 

task token. 



Stack not an iRMX segment 
TOKEN is not a TASK 



The stack of the task is not an iRMX segment, as 
is required. 

The value entered for the token is valid; 
however, it is not a task token. 



Example 

This example shows how the VU command responds when system calls are nested. The 
task for the example has called RQ$S$WRITE$MOVE of the Extended I/O System. 
RQ$S$WRITE$MOVE has called RQ$A$WRITE of the Basic I/O System. 
RQ$A$WRITE has called RQ$ RECEIVES MESSAGE to wait for the data transfer to be 
completed. 

Suppose that before the message arrives signaling the completion of the transfer, you enter 
the System Debugger and invoke the following VU command: 

. .VU 21C8 <CR> 
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The System Debugger responds by displaying the following: 



gate #0430 














Return cs : ip 


-09B8:576A 












216A:01B2 


01C8 216A 


01C8 


216A 


FFFF 1768 


1760 


1988 


216A:01C2 


1550 0000 


2148 


1FF8 


1440 2558 


2000 


2050 


(Nucleus) receive message 












1 




|....re 


sp$p. . . 


| . time. | .mbox. 


1 




gate #05B0 














Return cs : ip 


-09D8:08E7 












216A:01D4 


01E8 216A 


1F58 


0400 


0000 20E8 


2098 


2088 


216A:01E4 


1430 2048 


01F8 


20F8 


1400 0218 


0000 


01F8 


(BIOS) write 














1 


. . .excep$p. . . 


. .mbox. 


| . count 


| . . .buffer$p. . 


| .conn. 


1 


gate #0710 














Return cs : ip 


-09F8:06FA 












216A:0218 


0020 19F0 


0400 


0030 


19F0 2098 


2080 


2140 


216A:0228 


2058 0000 


0000 


20C8 


20C8 20C8 


20C8 


20C8 


(EIOS) write 


move 












1 


. . .excep$p. . . 


. .count 


| . . .buffer$p. . . | .conn 


•1 
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3.1 INTRODUCTION 

This chapter provides a sample PL/M-286 program that was developed on an Intel 310 
system running on an iSBC® 286/10 processor board with the iRMX II.4 Operating 
System. The terminal was a Hazeltine 1510. The code has compiled without errors; 
however, it does not run. The step-by-step process for using iSDM monitor and System 
Debugger commands to locate and fix the bug, then to test the corrected code is described 
in section 3.2. A scenario examining debugging techniques and additional commands is 
provided in section 3.3. 



3.2 SAMPLE PROGRAM 

This program includes three tasks. 

• An initialization task (called Init) creates a mailbox and the other two tasks. 

• Two tasks (called Alphonse and Gaston) exchange messages via mailboxes. 

The source code is listed in Figures 3-1, 3-2, and 3-3. For information on compiling and 
binding this code, see the iRMX® II Programming Techniques Reference Manual or the 
iRMX® I Programming Techniques Reference Manual. The following description explains 
how the program is supposed to work. 

The application code runs as a Human Interface (HI) program; therefore, the <name of 
the OBJECT file specified in BND286> is entered at the HI prompt. The task called Init 
runs first, creating a mailbox it catalogs in the root directory under the name "master." It 
creates the tasks Alphonse and Gaston then suspends itself. 
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When Gaston receives control, it gets the token for the mailbox created by Init (by looking 
up the name "master" in the root job's object directory). It then creates a segment (in 
which it will place a message) and a response mailbox (to which Alphonse will send a 
reply). Next it goes into a loop in which it places a message in the segment (after 
displaying it on the screen), sends the segment to the master mailbox, then waits at the 
response mailbox for a reply. 

When Alphonse receives control, it also gets the token for the mailbox created by Init (by 
looking up the name in the root job's object directory). It then goes into a loop in which it 
waits at the mailbox for a message and checks to see if the token it received is a segment. 
If it is a segment, Alphonse places its own message in the segment (after displaying it on 
the screen), then sends the segment to the response mailbox. If it isn't a segment, 
Alphonse drops out of the loop and deletes itself. 

By using the two mailboxes, the tasks Alphonse and Gaston are synchronized. Gaston 
sends a message to the first mailbox and waits at the second one before continuing. 
Alphonse waits at the first mailbox. When it receives a message, it sends a reply to the 
second mailbox and waits at the first for another message. This cycle continues for 6 
messages. 

After sending its sixth message, Gaston drops out of the loop. Instead of sending a 
segment to the master mailbox, Gaston displays a final message to the screen then sends 
the task token (the token for the Init task) to the mailbox. When Alphonse receives this 
token and finds it is not a segment, Alphonse drops out of its loop and deletes itself. 

To finish the processing, Gaston causes the Init task to resume processing (remember, the 
Init task suspended itself earlier). When Init takes over, it deletes both offspring tasks and 
issues an EXIT$IO$JOB system call to return control to the Human Interface level. 
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compact 








init: DO; 






DECLARE 


token 


LITERALLY 


'SELECTOR' ; 


DECLARE 


fifo 


LITERALLY 


'0'; 


DECLARE 


self 


LITERALLY 


'0'; 


DECLARE 


task$priority 


BYTE ; 




DECLARE 


calling$task 


TOKEN; 




DECLARE 


calling$tasks$ j ob 


TOKEN; 




DECLARE 


master$mbox 


TOKEN; 




DECLARE 


status 


WORD; 




DECLARE 


init$task$ token 


TOKEN; 




DECLARE 


gas ton$ task$ token 


TOKEN; 




DECLARE 


alphonse$task$ token 


TOKEN; 




DECLARE 


alphonse$start$add 


POINTER; 




DECLARE 


gaston$start$add 


POINTER; 




DECLARE 


gaston$ds 


WORD EXTERNAL; 




DECLARE 


alphonse$ds 


WORD EXTERNAL; 




DECLARE 


s tack$po inter 


POINTER; 




DECLARE 


stack$size 


WORD; 




DECLARE 


task$flags 


WORD; 




gaston: 








PROCEDURE EXTERNAL; 






END gaston; 






alphonse: 






PROCEDURE EXTERNAL; 






END alphonse; 







Figure 3-1. Example PL/M-286 Application (Init) 
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$ include ( : rmx : inc/nuclus . ext) 
$ include ( :rmx: inc/eios.ext) 

calling$tasks$job = SELECTOR$OF(NIL) ; 
calling$task - SELECTOR$OF(NIL) ; 

gaston$start$add = @gaston; 
alphonse$start$add = @alphonse; 
stack$pointer = NIL; 
stack$size = 500; 
task$flags = 0; 

init$task$token = RQ$GET$TASK$TOKENS ( 
self, 
@status) ; 

CALL RQ$CATALOG$OBJECT ( 
calling$tasks$j ob , 
init$task$ token , 
(§(4, 'init'), 
@status) ; 

master$mbox = RQ$CREATE$MAILBOX ( 
fifo, 
@status) ; 

CALL RQ$CATALOG$OBJECT ( 
calling$tasks$ j ob , 
master$mbox, 
@(6 , 'master' ) , 
@status) ; 

task$priority = RQ$GET$ PRIORITY ( 
calling$task, 
@status) ; 

task$priority - task$priority + 1; 



/* Directory obj cataloged in */ 

/* Task whose priority will */ 

/* be gotten */ 

/* Set up start addresses for */ 

/* tasks */ 

/* Values for creating tasks */ 



/* Get token for init task */ 



/* Catalog task token in */ 
/* directory of calling */ 
/* task's job */ 



/* Create mailbox tasks use */ 
/* to pass messages */ 



/* Catalog mailbox in */ 
/* directory of calling */ 
/* task's job */ 



/* Get priority of calling */ 
/* task */ 



/* Pick lower priority for */ 
/* new tasks */ 



Figure 3-1. Example PL/M-286 Application (Init) (continued) 



3-4 



System Debugger 



SAMPLE DEBUG SESSION 



alphonse$task$ token = RQ$CREATE$TASK ( /* Create tasks */ 

task$priority, 

alphonse$start$add f 

SELECTOR$OF(@alphonse$ds) , 

stack$pointer , 

stack$size, 

task$flags, 

^status) ; 

gas ton$task$ token = RQ$CREATE$TASK ( 
task$priority, 
gaston$start$add, 
SELECTOR$OF(@gaston$ds) , 
stack$pointer , 
stack$size, 
task$flags , 
@status) ; 

CALL RQ$SUSPEND$TASK ( /* Suspend self and let other */ 

call ing$ task, /* tasks run */ 

^status) ; 

CALL RQ$DELETE$TASK ( /* Clean up and exit */ 

gas ton$task$ token , 
@status) ; 

CALL RQ$DELETE$TASK ( 

alphonse$task$ token , 
^status) ; 

CALL RQ$EXIT$IO$JOB ( 
0, 

NIL, 
@status) ; 

END; /* Init */ 

Figure 3-1. Example PL/M-286 Application (Init) (continued) 
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$compact 
alphonse$code: DO; 



DECLARE token 



LITERALLY 



SELECTOR* 



$ include ( : rrax : inc/nuclus . ext ) 
$include( :rmx: inc/eios .ext) 
$include( :rmx: inc/hi .ext) 



alphonse: 










PROCEDURE PUBLIC; 








DECLARE 


CR 




LITERALLY 


'13'; 


DECLARE 


LF 




LITERALLY 


'10' ; 


DECLARE 


wait$forever 




LITERALLY 


'OFFFFH' 


DECLARE 


FOREVER 




LITERALLY 


'WHILE 1 


DECLARE 


calling$tasks$j 


ob 


TOKEN ; 




DECLARE 


master$mbox 




TOKEN; 




DECLARE 


response$mbox 




TOKEN; 




DECLARE 


status 




WORD 






DECLARE 


type$code 




WORD 






DECLARE 


time$limit 




WORD 






DECLARE 


count 




WORD 






DECLARE 


alphonse $ds 




WORD PUBLIC; 




DECLARE 


seg$token 




TOKEN; 




DECLARE 


seg$size 




WORD; 




DECLARE 


display$message 


(*) 


BYTE 


DATA( 


CR,LF, 'After you, 


Gaston' , CR, 


LF); 




DECLARE 


message BASED seg$ token 


STRUCTURE ( 










count 


BYTE, 








text(25) 


BYTE); 



time$limit = 25; 

seg$size = 32; 
calling$tasks$j ob 



= SELECTOR$OF(NIL) ; 



/* Delay factor for message */ 
/* display */ 

/* Size of message segment */ 
/* Directory in which to look */ 
/* up obj */ 



Figure 3-2. Example PL/M-286 Application (Alphonse) 
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master$mbox - RQ$LOOKUP$OBJECT ( 
calling$tasks$j ob , 
@(6, 'master' ) , 
wait$forever, 
@status) ; 



/* Look up message */ 
/* mailbox */ 



DO FOREVER; 



seg$token = RQ$RECEIVE$MESSAGE ( 
master$mbox, 
wait$forever , 
@response$mbox , 
@status) ; 



/* Receive response */ 
/* from Gaston */ 



type$code - RQ$GET$TYPE( 
seg$ token, 
^status) ; 

IF type$code O 6 THEN 

CALL RQ$EXIT$IO$JOB ( 
0, 

NIL, 
@status) ; 



/* 


See what kind 


of 


*/ 


/* 


object it is 




*/ 


/* 


If it isn't a 




*/ 


/* 


segment, exit 




*/ 



message. count = 21; 

CALL MOVB((§display$message, @message 



text, size(display$message) ) ; 



CALL RQ$C$SEND$CO$RESPONSE ( 
NIL, 



/* Send message to 
/^screen 


*/ 
*/ 


^message . count , 
@status) ; 






CALL RQ$ SLEEP ( 
time$limit, 
@status) ; 


/* Wait a while to 
/* give user time to 
/* see the message 


*/ 
*/ 
*/ 


CALL RQ$SEND$MESSAGE ( 
response$mbox , 
seg$ token, 
SELECT0R$0F(NIL) , 
^status) ; 


/* Send message to 
/* response mailbox 


*/ 
*/ 


END; 
END alphonse ; 
END alphonse$code; 


/* FOREVER 
/* Alphonse 


*/ 
*/ 


Figure 3-2. Example PL/M-286 


Application (Alphonse) (continued) 
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$compact 
gaston$code: DO; 

DECLARE token 

$ include ( : rmx: inc/nuclus . ext) 
$ include ( :rmx: inc/eios .ext) 
$ include ( : rmx : inc/hi . ext) 



LITERALLY 



'SELECTOR' ; 



gas ton: 








PROCEDURE PUBLIC; 




DECLARE 


CR 


LITERALLY 


DECLARE 


LF 


LITERALLY 


DECLARE 


fifo 


LITERALLY 


DECLARE 


wait$forever 


LITERALLY 


DECLARE 


parent$task 


TOKEN 




DECLARE 


calling$tasks$j ob 


TOKEN 




DECLARE 


master$mbox 


TOKEN 




DECLARE 


response$mbox 


TOKEN 




DECLARE 


status 


WORD; 




DECLARE 


time$limit 


WORD; 




DECLARE 


count 


WORD; 




DECLARE 


final$count 


WORD; 




DECLARE 


gaston$ds 


WORD PUBLIC; 


DECLARE 


seg$token 


TOKEN; 


DECLARE 


seg$size 


WORD; 


DECLARE 


main$message (*) 


BYTE 


CR,LF, 'After you, Alphonse' 


CR, LF) 


> 



DECLARE final$message(*) BYTE 

CR,LF, 'If you insist, Alphonse', CR, LF) ; 



DECLARE message BASED seg$token 



STRUCTURE ( 
count 
text(27) 



13'; 
10'; 
0'; 
OFFFFH' 



DATA( 
DATA( 



BYTE, 
BYTE); 



count = 0; 
final$count = 6; 
time$limit = 25; 

seg$size = 32; 
calling$tasks$ j ob 



SELECTOR$OF(NIL) ; 



/* Initialize count */ 

/* Set number of loops */ 

/* Delay factor for display */ 

/* to screen */ 

/* Size of message segment */ 

/* Directory in which to look */ 

/* up object */ 



Figure 3-3. Example PL/M-286 Application (Gaston) 
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master$mbox - RQ$LOOKUP$OBJECT ( 
calling$tasks$j ob , 
@(6 , 'master' ) , 
wait$forever , 
@status) ; 

response$rabox = RQ$CREATE$MAILBOX ( 
fifo, 
^status) ; 

seg$ token = RQ$CREATE$ SEGMENT ( 
seg$size, 
@status) ; 



/* Look up message mailbox */ 



/* Create response mailbox */ 



/* Create message segment */ 



DO WHILE count < final$count; 
message . count =23; 
CALL MO VW(@main$mes sage, @mes sage. text, SIZE(main$message)) ; 



CALL RQ$C$SEND$CO$RESPONSE ( 
NIL, 
0, 

(^message . count , 
@status) ; 

CALL RQ$ SLEEP ( 
time$limit, 
@status) ; 

CALL RQ$SEND$MESSAGE ( 
master$mbox, 
seg$ token, 
response$mbox , 
@status) ; 

seg$ token = RQ$RECEIVE$MESSAGE( 
response$mbox , 
wait$forever , 
NIL, 
@status) ; 

count = count + 1; 



/* Send message to screen 



*/ 



/* Wait a while to give user */ 
/* time to see the message */ 

/* Send message to mailbox */. 



/* Receive response from 
/* Alphonse 



*/ 
*/ 



END; 



/* WHILE 



*/ 



message. count = 27; 

CALL MOVB(@final$message,@message. text , SIZE(final$message) ) ; 



Figure 3-3. Example PL/M-286 Application (Gaston) (continued) 



System Debugger 



3-9 



SAMPLE DEBUG SESSION 



CALL RQ$C$SEND$CO$RESPONSE ( 

NIL, 

0, 

@message . count , 

@status) ; 



/* Send final message to */ 
/* screen */ 



CALL RQ$SEND$MESSAGE ( 
master$mbox, 
master$mbox, 
SELECT0R$0F(NIL) , 
@status) ; 

parent$task = RQ$L00KUP$0BJECT( 
calling$tasks$j ob , 
@(4,'init'), 
wait$forever, 
@status) ; 



/* Send token for mailbox */ 
/* to mailbox. This will */ 
/* stop other task. */ 



/* Look up token for */ 
/* calling task */ 



CALL RQ$RESUME$TASK( 
parent$task, 
@status) ; 



/* Resume calling task */ 
/* for cleanup */ 



END gas ton; 
END gaston$code; 



/* Gaston 



*/ 



Figure 3-3. Example PL/M-286 Application (Gaston) (continued) 
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3.3 DEBUGGING THE PROGRAM 

Although it's a good idea to include error checking when developing programs, we did not 
include any in our sample program so we could demonstrate more features of the System 
Debugger. The sample program contains one error. We will show two approaches to 
finding and correcting it using the System Debugger. 

The addresses and token values appearing in the following examples are those the system 
assigned in this debugging session. Most of these values will change from session to 
session. It's helpful to keep paper and pencil handy to note the various addresses and 
tokens. 

When the iSDM monitor is invoked, both the application code and the operating system 
code freeze. However, by using iSDM monitor and System Debugger commands you can 
disassemble and execute the application instructions. Thus, in a debugging session you will 
move the CS:IP through your code, examining system objects, possibly changing stack or 
register values. These changes are valid for only one pass through the code. To re-execute 
the code, kill the current job by using the CLI-restart feature, then re-enter the iSDM 
monitor by using the Human Interface DEBUG command. 

Example #1: 

When <name of OBJECT file specified in BND286> runs, the system displays the 
following message: 



Interrupt 13 at 2C38:0199 General Protection ECODE=0000 



The values 2C38:0199 are where the CS:IP was pointing when the program halted. The 
protected-mode prompt (..) indicates that we are in the iSDM monitor. However, since the 
program has been executed, we must re-enter the iSDM monitor to re-execute the code. 
We can use the CLI-restart feature to return to the Command Line Interpreter. Enter the 
following command: 

. .g 284:14 <CR> 

The system responds with the Human Interface prompt (-). Next, enter the following 
command: 

-Debug <name of OBJECT file specified in BND286> <CR> 
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The system responds with the following: 



Interrupt 3 at 2A70:FFFF 



Use the iSDM monitor's GO (G) command to set a breakpoint at the instruction where the 
program halted (remember the CS:IP value is given in the interrupt message displayed 
when the program halts). The code segment (CS) value will change each time you re-enter 
the iSDM monitor, but the instruction pointer (IP) will remain the same. Enter the 
following command: 

..g,199 <CR> 

To find out where we are in the code, use the iSDM monitor's D (DISPLAY 
MEMORY/DESCRIPTOR TABLES) command to display a disassembled block of code. 
Enter the following command: 

. . 10 dx , <CR> 

The system displays the following code: 



2500:0199 


F2A5 


REP 


MOVSW 


2500:019B 


B80000 


MOV 


AX, 0000 


2500:019E 


8BD0 


MOV 


DX,AX 


2500-.01A0 


52 


PUSH 


DX 


2500:01A1 


50 


PUSH 


AX 


2500:01A2 


680000 


PUSH 


0000 


2500:01A5 


8E063E00 


MOV 


ES,[003E] 


2500:01A9 


B80000 


MOV 


AX, 0000 


2500:01AC 


06 


PUSH 


ES 


2500:01AD 


50 


PUSH 


AX - 
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The instruction at address 2500:0199 is a MOVE STRING WORD command. The only 
move word instruction in the sample program is the PL/M-286 MOVW call when Gaston 
enters the loop after creating the segment. The following display shows this section of 
code: 



response$mbox = RQ$CREATE$MAILBOX ( /* Create response mailbox */ 

fifo, 
@status ; 



seg$ token = RQ$CREATE$SEGMENT( 
seg$size, 
^status ; 

DO WHILE count < final$count; 
mes sage. count , = 23; 



/* Create message segment */ 



CALL MOW(@main$message, @message. text , SIZE(main$message)) ; 



CALL RQ$C$SEND$CO$RESPONSE ( 
NIL, 
0, 

(^message . count , 
@status) ; 



/* Send message to screen */ 



Figure 3-4. MOVW in Gaston Code 



If displaying the instruction doesn't provide enough information about why the program 
halted, we can look at the surrounding code by displaying forward or backward from the 
CS:IP. The comma we specified in the DX command enables us to enter just a comma (,) 
now to display forward another ten instructions from the current CS:IP. (Displaying 
backward from the CS:IP is shown in Example #2.) To see the register contents, enter the 
following command: 

. .x <CR> 
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The system displays the following: 



AX=0000 CS=2500 IP=0199 FL=0293 RGDT .BASE=002000 .LIMIT=2FFF 

BX=0034 SS=2638 SP=01F2 BP=01F2 RIDT .BASE=005000 .LIMIT=03FF 

CX=0017 DS=2530 SI=0042 MSW=FFFB 

DX=2680 ES=2680 DI=0001 TR=0278 RLDT=02A0 



To execute the MOVSW instruction, enter the following command: 

. .n, <CR> 
The system displays the following: 



2500:0199 F2A5 REP MOVSW 



Enter a comma (,). 

The system responds with the following: 



Interrupt 13 at 2500:0199 General Protection ECODE=0000 



To see how executing this instruction changed register contents, enter the following 
command: 

. . x <CR> 
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AX=0000 
BX=0034 
CX=0006 
DX=26C0 



CS=2800 
SS=26D8 
DS=28B8 
ES=26C0 



IP=0199 
SP=01F2 
SI=0062 
DI=0021 



Fk=0293 

BP=01F2 

MSW=FFFB 

TR=0278 



RGDT .BASE=002000 .LIMIT=2FFF 
RIDT .BASE=005000 .LIMIT=03FF 

RLDT=02A0 



In the ASM286 Assembly language MOVSW instruction, DS:SI represents the source data 
is moving from; ES:DI is the destination. (For more information on MOVSW, see the 
ASM286 Assembly Language Reference Manual.) To check the limit of the ES register, 
enter the following command: 

. .ddt(es) <CR> 

The system displays the following: 



GDT (1427T) DSEG BASE=090484 LIMIT=001F P=l DPL=0 ED=0 W=l A=l 
SR=0000(ES) 



The LIMIT parameter shows that the segment limit is 1FH (31 decimal). Since the system 
counts from zero, the limit is 32 decimal which is the value assigned to seg$size in Gaston. 
The DI register (shown in the previous display) contains 21H (33 decimal), indicating the 
system was trying to write past the segment limit when the program halted. This fact 
suggests the PL/M-286 MOVW call should be changed to MOVB. Here we could exit the 
iSDM monitor, change the PL/M-286 code, then recompile and run it. 

However, we can use the iSDM monitor's EXAMINE/MODIFY REGISTERS (X) 
command to change a register value and the GO (G) command to execute the program. 
Making changes with the X and S (SUBSTITUTE MEMORY) commands enables us to 
test code without having to recompile and bind it. 

The CX register contains the count of bytes or words moved. If we decrease the count in 
the CX register to 15 before we execute the MOVSW instruction, we should be able to 
move all the data. Re-enter the iSDM monitor and set a breakpoint at the MOVSW 
instruction by entering the following commands: 



. .g 284:14 <CR> 

-debug <name of OBJECT file specified in BND286> 

..g,199 <CR> 



<CR> 
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Set the CX register to 15. Enter the following command: 

. .x cx=f <CR> 
Now, execute the rest of the program by entering the following command: 

. . g <CR> 
The system responds with the following: 



After 


you, 


Alphonse 












After 


you, 


Gaston 












Interrupt 


13 at 2A70 


0199 


General 


Protection 


ECODE= 


=0000 



Since our change was valid for one pass through the code, the first pass through the Gaston 
loop worked. The next pass failed. To return to the Command Line Interpreter, enter the 
following command: 

. .g 284:14 <CR> 

This partially successful run shows that if we reduce the number of words moved, the 
program works. Therefore, to make a permanent fix, we should change the PL/M-286 
MOVW call to MOVB in the sample code, then recompile and bind it. 

Example #2: 

We can also make changes in the disassembled code. Suppose we have run the program 
for the first time, and the system displayed the following message: 



Interrupt 13 at 2A70:0199 General Protection ECODE=0000 



Restart the system using the CLI-restart feature as you did in Example #1, then re-enter 
the iSDM monitor by entering the following command: 

-Debug <name of OBJECT file specified in BND286> <CR> 



3-16 System Debugger 



SAMPLE DEBUG SESSION 



Set a breakpoint at the instruction that was executing when the program failed and display 
a block of disassembled code by entering the following commands: 

..g,199 <CR> 
. . 5 dx <CR> 



The system displays the following: 



1258:0199 


F2A5 


REP 


MOVSW 


1258:019B 


B80000 


MOV 


AX.0000 


1258:019E 


8BD0 


MOV 


DX,AX 


1258:01A0 


52 


PUSH 


DX 


1258:01A1 


50 


PUSH 


AX 



To look at the instructions preceding MOVSW, enter the following command: 
. . 15 dx cs : ip - 25 <CR> 
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The system displays the following code: 



1258:0174 


8B063800 


MOV 


AX, [0038] 


1258:0178 


3B063A00 


CMP 


AX, [003A] 


1258:017C 


7203 


JB 


A-0181 


1258:017E 


E97600 


JMP 


A=01F7 


1258:0181 


B117 


MOV 


CL,17 


1258:0183 


8E063E00 


MOV 


ES, [003E] 


1258:0187 


26880E0000 


MOV 


ES: [0000] ,CL 


1258:018C 


B500 


MOV 


CH,00 


1258:018E 


8E063E00 


MOV 


ES, [003E] 


1258:0192 


BF0100 


MOV 


DI,0001 


1258:0195 


BE4200 


MOV 


SI, 0042 


1258:0198 


FC 


CLD 




1258:0199 


F2A5 


REP 


MOVSW 


1258:019B 


B80000 


MOV 


AX, 0000 


1258:019E 


8BD0 


MOV 


DX,AX 



MOVSW is a repetitive move from DS:SI to ES:DI. Looking at the preceding instructions, 
we see 1258:0181 moves 17H into CL, which is the low-order register of CX. Remember 
that CX is the count of bytes or words moved. (For more information on the register set, 
see the ASM286 Assembly Language Reference Manual). If we display the ES register 
contents using "ddt(es) < CR> " as we did in the last example, we can check the limit. Since 
the limit is 32 (decimal) and the system is trying to write 17H words, the system fails when 
it tries to write past the segment limit. If we reduce this count we should be able to move 
the data. We must re-enter the iSDM monitor, then using the iSDM monitor's 
SUBSTITUTE (S) command, we can change the code at 1258:0181. Semicolons (;) 
precede the explanations in the following code; enter the information appearing in blue: 

. .g 284:14 <CR> 

-Debug <name of OBJECT file specified in BND286> <CR> 

..s cs:181 <CR> ; enter monitor command to substitute 

; memory at Ip=0181 
1258:0181 Bl - , ; enter a comma to step to the count 

1258:0182 17 - f <CR> ; enter the new count 
. .g <CR> ; re -start code execution 
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The system responds with six iterations of the following: 



After you, Alphonse 
After you, Gaston 



After six iterations of the previous screen, the monitor displays the following: 



If you insist, Alphonse 
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3.4 VIEWING SYSTEM OBJECTS 

Consider that we have a deadlock problem. By looking at system objects at various stages 
of execution, we can observe how synchronization (or lack of it) is occurring. 

We can view any object in a job using the VO command (specifying the job's token) to 
provide the broad picture of the system state, then the VT command to focus on individual 
elements. Suppose, we want to view the state of the objects before entering the loop in 
which Gaston and Alphonse exchange messages. Assume we have stepped through the 
code, verifying system calls until we located the CS:IP for the Nucleus create$segment 
system call in Gaston. Re-enter the iSDM monitor and set a breakpoint at this CS:IP by 
entering the following commands: 

-Debug <name of OBJECT file specified in BND286> <CR> 
..g,16d <CR> 

To get the job token, enter the following command: 

. . v j <CR> 

The system displays the following: 



iRMX® <I/II> Job Tree 

0258 

0F38 

1670 

2460 
0E88 
0E00 



Note that "2460" is the token for the application job. To view objects for this job, enter the 
following command: 



vo 2460 <CR> 
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The system displays the following: 



Child Jobs: 
















Tasks : 


26D0 


26F0 


1AC8 


1900 








Mailboxes : 


25C0 t 


1AB8 












Semaphores : 
















Regions : 
















Segments : 


25B0 


25E8 


25E0 


2650 


2528 


2480 


2478 


Extensions : 
















Composites : 


24A0 















At this stage of program execution, two mailboxes exist. The "t" following mailbox 25C0 
means one or more tasks are waiting at it (Alphonse was created first and is waiting for a 
message from Gaston). Examine mailbox 25C0 by entering the following command: 

. .vt 25C0 <CR> 
The system responds with the following: 



Object type = 3 


Mailbox 




Task queue head 


1900 Object queue head 


0000 


Queue discipline 


FIFO Object cache depth 


08 


Containing job 


2460 




Task queue 


1900 





Use the System Debugger's VU command to view the waiting task's stack. To unwind the 
stack, enter the following command: 

. .vu 1900 <CR> 
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The system displays the following: 



gate #0430 










Return cs : ip - 1D18:029F 










16C8:01E6 0086 1D28 


0084 1D28 


FFFF 


17E0 


0000 


(Nucleus) receive message 










| . . .excep$p. . . 


| resp$p 


| . time . 


.mbox. | 





We can continue to examine objects or set a breakpoint at the return CS:IP. Setting the 
CS:IP (g, 29f < CR> ) in the sample program causes the iSDM monitor to display the 
following: 



Interrupt 13 at 21F0:0199 General Protection ECODE=0000 



This message indicates that the program halts in Gaston and that 21F0:0199 is the 
instruction executing when it dies. 

This chapter has shown two ways to find an error and two ways to make temporary fixes 
from the System Debugger. The message displayed when the program halts contains the 
CS:IP of the last instruction executing. If setting the CS:IP at this instruction and 
displaying the surrounding code doesn't give you enough information about where this 
point is in your application code, you can use combinations of VJ, VO, VT, VU, and YS to 
locate the running task. Then set the breakpoint at the CS:IP of the last executing 
instruction and display code, objects, and registers to determine how the system is 
executing that instruction. 
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A.1 INTRODUCTION 

This appendix briefly describes the iSDM System Debug Monitor commands in 
alphabetical order. A command directory listing the functional groups and page references 
precedes the command descriptions. For examples and more detailed information about 
the commands, see the iSDM™ System Debug Monitor User's Guide. 



A.2 COMMAND DIRECTORY 

This section provides a brief summary of all iSDM monitor commands listed by functions. 
Each entry in the following summary contains along with the command name a brief 
description of the command and a page reference where you can find more information on 
the command. 



Command Function Performed Page 



PROGRAM LOADING AND EXECUTION 

B Bootstrap load code from the target system's 

secondary storage into the target system's memory A-3 

G Begin executing application program A-5 

L* Load an 8086 absolute object file or an 80286 
object file from a development system into 
target system memory A-6 

N Execute one or more instructions at a time A-6 

R* Load and execute an 8086 absolute object file or an 

80286 absolute object file in target system memory A-7 
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Command Function Performed Page 



I/O PORT INPUT AND OUTPUT COMMANDS 

I Input and display a byte or word from the specified 

port A-5 

O Output a byte or word to the specified port A-7 



BLOCK MANIPULATION 

C Compare the contents of one block of memory with 

that of another block A-4 

F Search the specified block of memory for a sequence 

of hexadecimal digits A-5 

M Copy the content of a block of memory to another 

block of memory A-6 



MEMORY/REGISTER DISPLAY AND MODIFICATION 

D Display the contents of memory and descriptor table 

entries A-4 

S Display and (optionally) modify memory locations and 

descriptor table entries A-8 

X Display and/or modify CPU/NPX register or task state 

segment contents A-9 
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Command Function Performed Page 

MISCELLANEOUS COMMANDS 

E* Exit the loader program. Return control to the 

development system A-4 

K* Echo all console output to a file A-5 

P Display the base and offset portion of an address 

or an expression A-7 

Q Enable Protected Virtual Address Mode (protected 

mode) A-7 

Y* Display and define symbol information A-9 

* Command requires an attached development system. 



A.3 COMMAND DESCRIPTIONS 

This section provides brief descriptions for iSDM monitor commands in an easily 
referenced alphabetical order. For more information on command parameters, syntax, and 
options, refer to the iSDM™ System Debug Monitor User's Guide. 

A.3.1 B-Bootstrap Load 

The B command passes control to the bootstrap loader to load absolute object code from 
secondary storage into your target system memory. The Bootstrap Loader loads the file 
into the target system at the memory address specified in the file. After the bootstrap 
loader finishes loading the file, the code begins executing. To use the B command 
correctly, you must be operating in real mode. 

If either the file you specified or the default file does not exist, the bootstrap loader halts 
and takes action according to how it is configured. 



System Debugger A-3 



iSDM™ MONITOR COMMANDS 



A.3.2 C-Compare 

The C command compares the contents of one block of memory defined by a range with 
the contents of another block of memory that begins at a destination address. The iSDM 
monitor expects the blocks to be equal in length. If the iSDM monitor encounters any 
mismatched bytes, it displays them in the following format: 

aaaarbbbb xx yy aaaa:bbbb 

where "aaaa:bbbb" are the addresses of the bytes that do not match and "xx" and "yy" are 
the bytes themselves. 

A.3.3 D--Display Memory/Descriptor Tables/Disassembled 
Instructions 

The D command is actually three commands in one. You can use it to display the contents 
of a specified block of memory, the contents of an 80286/386 descriptor table, or the 
contents of a specified block of memory in disassembled form. If you are operating in real 
mode, you cannot display descriptor table entries. However, if you are operating in 
protected mode, you can use both functions of this command. 



A.3.4 E--Exit 

The E command enables you to exit the loader program by returning control from the 
loader program to the development operating system. Upon return, the iSDM monitor 
loses all symbol information. 

When using the E command, you must use it on a line by itself; do not use multiple 
commands on a line with the E command. Also, your system must include an attached 
development system before you can use this command. 

When you reinvoke the iSDM monitor after exiting the loader program, one of two things 
happens: 

• The iSDM monitor prints either a single or double prompt depending upon whether 
you were operating in real or protected mode when you exited. 

• The iSDM monitor prints its usual sign-on message and re-initializes itself if you reset 
your target system between the time you exited the loader and the time you reinvoked 
the iSDM monitor. 
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A.3.5 F-Find 

The F command searches the block of memory you specified to determine if it contains the 
sequence of hexadecimal digits you chose in the data parameter. Each time the iSDM 
monitor finds a match, it displays the address of the first matching byte. 

A.3.6 G-Go 

The G command instructs the iSDM monitor to begin executing your application program. 
In response to the G command, the iSDM monitor single steps the first instruction, then 
executes all succeeding instructions at full speed. 

Your application program must have at least 12 bytes of stack available for the iSDM 
monitor to use. If you are operating in protected mode, each task in your program must 
contain at least 12 bytes of stack at privilege level for the iSDM monitor to use. 

With 80286 and 386 boards, a special situation arises when you execute the G command 
and you specify a breakpoint address but not a starting address. If the breakpoint is in an 
interrupt handler and the current CS:IP is at a software interrupt instruction (INT x, 
INTO, BOUND), the iSDM monitor single steps the interrupt instruction, executing the 
interrupt handler at full speed and bypassing the breakpoint you set. To get around this 
80286/386 operational anomaly, make sure that the CS:IP is pointing to the (or any) 
instruction preceding the software interrupt instruction before you execute the 
G command. 



A.3.7 l-Port Input 

The I command retrieves and displays a byte or word from the port you specify. Byte and 
word formats are different. (See the iSDAT* System Debug Monitor User's Guide for byte 
and word format descriptions). 



A.3.8 K-EchoFile 

The K command copies all console output to a development system file you specify. 
Repeating the K command without specifying a file causes the iSDM monitor to stop 
copying console output. Your system must include an attached development system in 
order to use this command. 
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A.3.9 L--Load Absolute Object File 

The L command loads absolute 8086 or 80286 object files into target system memory. The 
iSDM monitor loads the data from the file into the memory location that you specified 
when you used the LOC86 or BLD286 commands. When loading the data, the iSDM 
monitor discards all previously loaded symbol information and loads the new symbol 
information, but it retains all user-defined symbols. If the file contains a register 
initialization record, the iSDM monitor sets the appropriate registers to the values the file 
specifies. Your system must include an attached development system in order to use this 
command. 

The L command cannot load relocatable modules. If you are operating in real mode, you 
can load only 8086 absolute object files. If you are operating in protected mode, you can 
load only 80286 absolute object files. 

When you load an 80286 object file, the iSDM monitor initializes the first 40 global 
descriptor table (GDT) entries for its own use. In addition, the iSDM monitor initializes 
any uninitialized interrupt descriptor table (IDT) entries. If the access byte is equal to 
zero, the iSDM monitor assumes that the descriptor table entry is not initialized. Refer to 
Intel's Microprocessor and Peripheral Handbook, Microsystem Components Handbook, or 
80286 Operating System Writer's Guide for more information about the descriptor tables. 

A.3.10 M-Move 

The M command copies the contents of a block of memory to a memory address you 
specify. 

A.3.1 1 N-Execute Single Instructions 

The N command displays and executes one or more disassembled instructions at a time. 
Going through your application line-by-line is called "single-stepping." Single-stepping 
allows you to begin at a CS:IP you specify and check your application for problems in an 
instruction-by-instruction manner. 

Your application program must have at least 12 bytes of stack available for the iSDM 
monitor to use. If you are operating in protected mode, each task in your program must 
contain at least 12 bytes of stack at privilege level for the iSDM monitor to use. 

When you are single-stepping instructions, you should be aware of some special 
considerations. See the iSDM™ System Debug Monitor User's Guide for more information 
about these special considerations when using the N command. 
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A.3.12 0--Port Output 

The O command allows you to enter data (a byte or word) at the console and send it to a 
port you select. 



A.3.13 P-Print 

The P command allows you to display either the value of an expression or the value of the 
base (or selector) and offset portions of an address. The values are displayed on your 
console terminal screen. The iSDM monitor always displays an address in hexadecimal 
form. If you enter "P" plus an expression, the iSDM monitor prints the value in 
hexadecimal. If you enter "PT" or "PS" plus an expression, the iSDM monitor prints the 
value in decimal or signed decimal form, respectively. 

In this command, the comma acting as a separator also causes the iSDM monitor to add a 
space between the addresses or expressions it displays. 

A.3.14 Q-Enable Protection (80286 or 386™ Only) 

The Q command changes the 80286- or 386-based system from real mode to protected 
mode. The iSDM monitor displays the following message when you use the Q command: 



Now in Protected Mode 



When you invoke this command, the iSDM monitor initializes the entries it needs in the 
GDT and the IDT. The iSDM monitor then places itself at privilege level zero. If you are 
already operating in protected mode when you invoke this command, the iSDM monitor 
re-initializes the GDT and IDT entries. The only way you can return to real mode is to 
reset the 80286 or 386 hardware. 



A.3.15 R-Load and Go 

The R command is a combination of the Load command (L) and the Go command (G). 
This command loads an absolute object file from a development system into target system 
memory then executes this program. This command causes the iSDM monitor to discard 
all previously loaded symbol information and load new symbol information; however, the 
iSDM monitor retains all user-defined symbols. Your system must include an attached 
development system in order to use this command. 
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The iSDM monitor loads the data from the file into the memory location that you specified 
when you used the LOC86 or BLD286 commands. If the file contains a register 
initialization record, the iSDM monitor sets the appropriate registers to the values the file 
specifies. 

The R command cannot load relocatable modules. If you are operating in real-addressing 
mode, you can load only 8086 absolute object files. If you are operating in protected mode, 
you can load only 80286 bootloadable (absolute) files. 

When you load an 80286 object file, the iSDM monitor initializes the first 40 global 
descriptor table (GDT) entries for its own use. In addition, the iSDM monitor initializes 
any uninitialized interrupt descriptor table (IDT) entries. Refer to Intel's Microprocessor 
and Peripheral Handbook, Microsystem Components Handbook, or 80286 Operating System 
Writer's Guide for more information about the 80286 component's descriptor tables. 

After the iSDM monitor loads the file and sets the appropriate registers to the values the 
file specifies, it begins to execute the program at the location specified by the CS and IP 
registers. 

Your application program must have at least 12 bytes of stack available for the iSDM 
monitor to use. If you are operating in protected mode, each task in your program must 
contain at least 12 bytes of stack at privilege level for the iSDM monitor to use. 

A.3.16 S--Substitute Memory/Descriptor Table Entry 

The S command is actually two commands in one. You can use it to display and 
(optionally) modify either the contents of memory or the contents of descriptor table 
entries. If you are operating in real mode, you cannot display and modify descriptor table 
entries. However, if you are operating in protected mode, you can use both functions of 
this command. 

If you enter the S command without an equal sign ( = ), the iSDM monitor displays a 
special hyphen (-) prompt. Then, it waits for you to enter either 

• A continuation comma instructing the iSDM monitor to display the next memory 
location. 

• A single expression or a list of expressions separated by slashes (/). By entering an 
expression (or expressions), you instruct the iSDM monitor to substitute these values in 
place of those already in the memory location you specified. 

The iSDM monitor continues to issue hyphen prompts until you enter a carriage return. 
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A.3.17 X-Examine/Modify Registers 

The X command allows you to examine and (optionally) modify the contents of your 
system's NPX and microprocessor registers. 

If you use the X command with no parameters, the iSDM monitor displays all the 8086, 
286, and 386 registers (except for control and debug registers). 

If you use both the register name and an expression, (for example, CS = XXXX), the value 
you entered (XXXX) is placed in the specified register. 

You can use the X command to set the 8086 family and NPX registers and the task state 
segment contents to any value. If you used any invalid values, the iSDM monitor reports 
them when you execute the application program. 

A.3.18 Y--Symbols (80286 or 386™ Only) 

The Y command allows you to display and define symbol information generated by 80286 
translators. If you use the Y command with no parameters, the iSDM monitor displays all 
the symbols stored in the current domain module or in all modules if you set no domain. 
You can also choose to have the iSDM monitor display the symbols and their values in a 
particular module or you can use this command to define your own symbols. To use this 
command, you must be operating in protected mode, with an attached development 
system. 



System Debugger A-9 



D-MON386 COMMANDS 



B 



B.1 INTRODUCTION 

This appendix briefly describes the 386™ Debug Monitor (D-MON386) commands in 
alphabetical order. A command directory listing the functional groups and page references 
precedes the command descriptions. For examples and more detailed information about 
the commands, see the D-MON386 Debug Monitor for the 80386 User's Guide. 

B.2 ENTERING COMMANDS 

To enter D-MON386 commands, follow the guidelines below: 

• End a command line by pressing the ENTER key or the RETURN ( < CR > ) key. A 
command line can consist of one or more commands. 

• Separate multiple commands on a single line using a semicolon (;). 

• Continue commands from one line to another by entering the slash (/) just before 
terminating the line with the ENTER key or RETURN key. 

• Enter commands using upper or lower case characters. 

• Use CTRL-C (pressing the control key down while at the same time pressing the C 
key) to abort a command being constructed on the command line. 
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B.3 COMMAND DIRECTORY 



This section provides a brief summary of all D-MON386 commands listed by functions. 
Each entry in the following summary contains along with the command name a brief 
description of the command and a page reference where you can find more information on 
the command. 



Command Function Performed Page 

BLOCK 



COUNT/ENDCOUNT Provides monitor command control 

structures. These structures enable you 
to enter and repeat execution of several 
monitor commands B-5 



CONTROL VARIABLES 



$ Display or set the current execution point B-5 

BASE Display or set the base number system to 

to either binary, octal, decimal, or 
hexadecimal B-5 

N0-N9 Display or set scratch registers zero 

through nine B-8 



EXPRESSION DISPLAY 



EVAL Evaluates an expression and displays the 

results B-7 
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Command 



Function Performed 



Page 



EXECUTION ENVIRONMENT 

GO Controls high-level execution environment B-8 

ISTEP Enables single-step execution B-9 

SWBREAK Displays and sets software code breaks B-10 

SWREMOVE Removes software code breaks B-ll 

DESCRIPTOR TABLE ACCESS 

DT Displays the Global or Local Descriptor 

tables B-7 

GDT Displays the Global Descriptor Table or 

specific entries B-8 

IDT Displays the Interrupt Descriptor Table or 

specific entries B-8 

LDT Displays the Local Descriptor Table or 

specific entries B-9 

MEMORY ACCESS 

ASM Disassembles memory as 386 assembler 

mnemonics B-6 

BYTE Reads or writes bytes of memory B-6 

DWORD Reads or writes double words of memory B-7 

INTn Reads or writes 1-, 2-, or 4-byte integers 

in memory B-8 

ORDn Reads or writes 1-, 2-, or 4-byte ordinals 

in memory B-9 
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Command 



USE 



WORD 



PAGE TABLE ACCESS 



PD 



PORT I/O 

DPORT 

PORT 

WPORT 



REGISTER ACCESS 

CREGS 
FLAGS 

Register-name 
REGS 

SREGS 



Function Performed Page 

Initializes the default for disassembling 

code to 16-bit or 32-bit B-ll 

Reads or writes words of memory B-ll 

Displays the Page Table Directory or page 

table entries B-10 

Reads or writes 32-bit ports B-8 

Reads or writes 8-bit ports B-ll 

Reads or writes 16-bit ports B-13 

Displays the control registers B-8 

Displays the lower 16 bits of the EFLAGS 

register in mnemonic form B-8 

Displays or modifies individual registers B-ll 

Displays a set of selected registers as a 

group B-ll 

Displays the segment registers as a group B-ll 



B-4 
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Command 



Function Performed 



Page 



TASK STATE SEGMENT ACCESS 



TSS 



Displays the contents of a task state 
segment 
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USER AID 



BOOT 
HELP 
HOST 

VERSION 



Executes a real mode interface program B-7 

Displays the help screen B-9 

Provides the capability for operation with 

PMON host software B-9 

Displays the version of D-MON386 B-12 



B.4 COMMAND DESCRIPTIONS 

This section provides brief descriptions for D-MON386 commands in an easily referenced 
alphabetical order. For on-line syntax help, refer to the HELP command. For more 
information on command parameters, syntax, and options, refer to the D-MON386 Debug 
Monitor for the 80386 User's Guide. 

B.4.1 $ 

This command displays or modifies the current execution point via the execution address 
register (CS:EIP). The contents of CS:EIP determine which ASM386 statement executes 
next. Entering $ by itself displays the current contents of CS:EIP. 
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B.4.2 ASM 



This command disassembles code into ASM386 opcode mnemonics. Using this command 
and the addresses you supply with it, you can disassemble from one to several lines of code. 
Disassembled code appears on the screen in column form. Each row of columns contains 
an address, a hexadecimal object value, an opcode mnemonic, any operands, and 
comments appended to the operands. 

B.4.3 BOOT 

This command invokes a user-supplied real mode interface program. The B command is 
intended primarily for including a bootstrap loader program. 

B.4.4 BASE 

This command displays or modifies the number base. Available number bases include 
binary, octal, decimal, and hexadecimal. The hexadecimal base is the monitor default base. 
Entering BASE by itself displays the current base. Entering BASE followed by an 
expression that evaluates to 2, 8, 10, or 16 (all decimal numbers) sets the base to binary, 
octal, decimal, or hexadecimal, respectively. 

B.4.5 BYTE 

This command displays or modifies partitions of memory using a byte format. You can 
specify the partition as a single byte or a range of bytes. Entering the command BYTE 
followed by an address or range of addresses causes that partition of memory to appear on 
the screen. Entering the command BYTE as an equation causes the partition of memory 
on the left side of the equation to be replaced with the contents of memory or value of the 
right side of the equation. 

B.4.6 COUNT/ENDCOUNT 

This command executes groups of D-MON386 commands in a specified order for a 
specified number of times. After entering COUNT expr, simply enter commands you wish 
to execute. After entering ENDCOUNT, one iteration of the commands will have already 
been executed. The entire group of commands then continues to execute for expr-1 
number of times. 

B.4.7 CREGS 

This command displays the contents of the control registers and the EFLAGS register 
when the processor is in real mode. If the processor is in protected mode, the CREGS 
command also displays the system address registers TR and LDTR. The display appears 
using a hexadecimal number base. 
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B.4.8 DPORT 

This command reads or writes a 32-bit port. Entering DPORT with the physical 
input/output address space as a 16-bit unsigned quantity causes the specified port to be 
read and the contents to appear on the screen. If you supply an expression to the right of 
the equal sign when entering this command, the addressed port is written with the value 
the expression equals. 

B.4.9 DT 

This command displays descriptors from either the LDT or the GDT depending upon the 
index supplied with the command. 

B.4.10 DWORD 

This command displays or modifies partitions of memory using a double word format. You 
can display a specific double word or a range of double words by entering DWORD 
followed by the single address or the range of addresses. Entering the DWORD command 
as an equation causes the partition of memory specified on the left-hand side of the 
equation to be replaced with the contents of memory or value of the right-hand side of the 
equation. 

B.4.11 EVAL 

This command evaluates the expression entered after the keyword EVAL. The results of 
the expression appear on the screen in binary, octal, decimal, hexadecimal, and ASCII 
formats. 

B.4.12 FLAGS 

This command displays the contents of the lower 16 bits of the EFLAGS register. The 
display appears in a mnemonic form. The presence of a mnemonic indicates a flag is set. 
The absence of a mnemonic in the display indicates a flag is not set. 

B.4.13GDT 

This command displays the entire Global Descriptor Table (GDT) or individual GDT 
descriptors. Entering the keyword GDT by itself causes the entire GDT to appear. 
Entering GDT followed by an index expression causes a specific descriptor to appear. 
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B.4.14 GO 

This command supplies high-level execution control. Use of the GO command enables you 
to begin and end program execution using specific points in the application. You can also 
clear and specify break conditions using the GO command. 

B.4.15 Help 

This command displays the major D-MON386 commands along with their general syntax. 
For examples and more detailed information about the commands, see the D-MON386 
Debug Monitor for the 80386 User's Guide. 

B.4.16 HOST 

This command provides the capability for operation with PMON host software. When 
entering this command, be sure to press only the ENTER key or a carriage return <CR> 
immediately after HOST. 

B.4.17 IDT 

This command displays the entire Interrupt Descriptor Table (IDT) or individual IDT 
descriptors. Entering the keyword IDT causes the entire IDT to appear. Entering IDT 
followed by an index causes a specific descriptor from the IDT to appear. 

B.4.18 INTn 

This command displays or modifies partitions of memory using an integer format. When 
entering the command, you can substitute the numbers 1, 2, or 4 for n. Thus, the integer 
type(s) referenced in memory are either 1-, 2-, or 4-byte integers. You can specify the 
partition as a single INTn value or a range of INTn values. Entering the command INTn 
followed by an address or range of addresses causes that partition of memory to appear on 
the screen. Entering the command INTn as an equation causes the partition of memory on 
the left side of the equation to be replaced with the contents of memory or value of the 
right side of the equation. 

B.4.19 ISTEP 

This command does single-step execution. You can use this command to single-step 
through the executable code from one to 255 executable statements. ISTEP also provides 
the capability to begin execution from a point other than the current execution point. 
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B.4.20 LDT 

This command displays the entire Local Descriptor Table (LDT) or individual LDT 
descriptors. Entering the keyword LDT causes the entire LDT to appear. Entering LDT 
followed by an index causes a specific descriptor from the LDT to appear. 

B.4.21 N0-N9 

This command displays or alters scratch registers zero through nine. Entering Nn (where n 
is a number through 9) by itself causes the value of the appropriate register to appear on 
the screen. You can enter Nn followed by an equal sign and an expression to alter the 
contents of the appropriate scratch register. 

B.4.22 ORDn 

This command displays or modifies partitions of memory using an ordinal format. When 
entering the command, you can substitute the numbers 1, 2, or 4 for n. Thus, the ordinal 
type(s) referenced in memory are either 1-, 2-, or 4-byte ordinals. You can specify the 
partition as a single ORDn value or a range of ORDn values. Entering the command 
ORDn followed by an address or range of addresses causes that partition of memory to 
appear on the screen. Entering the command ORDn as an equation causes the partition of 
memory on the left side of the equation to be replaced with the contents of memory or 
value of the right side of the equation. 

B.4.23 PD 

This command examines the Page Table Directory and page tables. When paging is 
enabled, the 386 uses two levels of tables to translate a linear address into a physical 
address: the Page Table Directory and the page tables themselves. Entering the PD 
command by itself causes the entire 4K Page Table Directory to scroll to the screen. You 
can, however, supply an index with the PD command to view a particular directory entry 
within the Page Table Directory. Also, you can use the additional .PT option with an index 
to view a particular page table entry. 

B.4.24 PORT 

This command reads or writes a 8-bit port. Entering PORT with the physical input/output 
address space as a 16-bit unsigned quantity causes the specified port to be read and the 
contents to appear on the screen. If you supply an expression to the right of the equal sign 
when entering this command, the addressed port is written with the value the expression 
equals. 
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B.4.25 Register-name 

D-MON386 enables you to display or alter the contents of 386™ registers. To gain register 
access, enter the name of the register Entering the name of the register only causes the 
contents of the register to appear on the screen. Entering the name of the register 
followed by an equal sign and a valid expression causes the contents of the register to be 
written with the value of the expression. For a complete list of register names, refer to the 
D-MON386 Debug Monitor for the 80386 User's Guide. 



NOTE 

Register modification is dependent on the current processor protection model. 
You cannot modify protected registers. 

B.4.26 REGS 

This command displays the contents of a set of registers as a group. The register set 
depends on which mode the processor is operating under (real or protected). The display 
is always in hexadecimal, and it provides less detail for the segment and control registers 
than the command that are specifically designed for those groups of registers, that is 
SREGS and CREGS, respectively. 

B.4.27 SREGS 

This command displays, in hexadecimal, the contents of the segment registers (CS, DS, SS, 
ES, FS, and GS). 

B.4.28 SWBREAK 

This command displays or sets code patch breaks. Entering SWBREAK by itself causes all 
current software break definitions to appear. If you enter SWBREAK followed by an 
equal sign and one or more addresses, the command sets a software break at the specified 
address or addresses. 



NOTE 

When specifying software break addresses, the address must be able to be 
written, present in physical memory, and on an instruction boundary. A 
maximum of 16 software breaks may be in effect at one time. 
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B.4.29 SWREMOVE 

This command removes all or selected code patch breaks. Entering this command followed 
by ALL removes all current software breaks. If you supply one or more addresses with the 
command, the software breaks at those addresses alone are removed. 

B.4.30 TSS 

This command displays the contents of a task state segment. TSS supports both 386 and 
80286 task state segments. Task state segments appear using the component names. 

B.4.31 USE 

This command specifies the default (16-bit or 32-bit code) for disassembling code from 
physical or linear addresses. When entering the command, the expression to the right of 
the equal sign must evaluate to either 16 or 32 (decimal). 

B.4.32 VERSION 

This command displays the version number of the D-MON386 software you are using. 

B.4.33 WORD 

This command displays or modifies partitions of memory using a word format. You can 
specify the partition as a single word or a range of words. Entering the command WORD 
followed by an address or range of addresses causes that partition of memory to appear on 
the screen. Entering the command WORD as an equation causes the partition of memory 
on the left side of the equation to be replaced with the contents of memory or value of the 
right side of the equation. 

B.4.34 WPORT 

This command reads or writes a 16-bit port. Entering WPORT with the physical 
input/output address space as a 16-bit unsigned quantity causes the specified port to be 
read and the contents to appear on the screen. If you supply an expression to the right of 
the equal sign when entering this command, the addressed port is written with the value 
the expression equals. 
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A 

Altering descriptor table entries A-8 
Altering memory contents A-8, B-6,7,8,9, B-ll 
Altering register contents 3-9, 3-16, A-9, B-10 

B 

Bootloading from the monitor A-3, B-6 
Bootstrap Loader DEBUG switch 1-3 
Breakpoints 1-3, 3-12, B-10, 11 

c 

Changing current instruction pointer B-5 
Changing descriptor table entry contents A-8 
Changing disassembled code 3-16, 3-18 
Changing memory contents A-8, B-6,7,8,9, 11 
Changing modes A-7 

Changing register contents 3-16, A-9, B-9,10 
CLI-restart 1-4, 1-restart 2-4, 3-11 
Code blocks, displaying 3-13, 3-17 
Commands 1-4, 2-1 

D-MON386 B-l 

Directory 2-5 

iSDMA-1 

Overview 1-4 

Syntax 1-4 

Syntax for debugger 2-3 

Token validity 2-2 

VB2-6 

VC 2-10 

VD2-13 

VF2-16 

VH2-18 

VJ 2-20 

VJ 3-20 

VK2-24 

VMF 2-26 

VMI 2-28 

VMO 2-32 

VO 2-36 
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VO 3-20 

VR2-39 

VS2-43 

VT2-48 

VT 3-20, 3-21 

VU2-74 

VU3-21 
Comparing blocks of memory A-4 
Configuration 1-2 
Contents of the stack 2-43 
Conventions 2-1 
Copying blocks of memory A-6 
Current instruction, displaying 3-12, B-5 

D 

D-MON386 monitor commands 
$B-5 
ASM B-6 
BB-6 
Base B-6 
Byte B-6 

Count/Endcount B-6 
CREGS B-6 
Directory B-2 
DPORTB-7 
DTB-7 
DWORD B-7 
EVALB-7 
FLAGS B-7 
GDTB-7 
GoB-8 
Help B-8 
Host B-8 
IDT B-8 
INTn B-8 
Istep B-8 
LDTB-9 
N0-N9 B-9 
ORDn B-9 
Overview B-1,5 
PDB-9 
Port B-9 

Register name B-10 
Regs B-10 
Sregs B-10 
Swbreak B-10 
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SwremoveB-11 

Syntax B-l 

TSS B-ll 

Use B-l 1 

Version B-ll 

Word B-ll 

WportB-11 
Deadlock 3-20 
DEBUG command 1-3, 3-11 
Debug session, sample 3-1 
Descriptor tables, displaying A-4, B-7,9 
Determining the base and offset of an address A-7 
Disassembled code, displaying 3-17, A-4, B-6,11 
Display symbol information A-9 
Displaying blocks of code 3-13, A-4 
Displaying the number base B-6 
DUIB information, displaying 2-6 

E 

Echoing console output A-5 

ES register limit, checking 3-15 

Examining a mailbox 3-21 

Examining page table directory and tables using D-MON386 B-9 

Examining register contents 3-13, 3-14, B-6,7,10 

Examining stack contents 3-21 

Example debug session 3-1 

Executing a program 3-16, A-5,7, B-8 

Executing a single line of code 3-14, A-6, B-8 

Exiting the monitor A-4 

Expression evaluation A-7, B-7 

F 

Fail-safe timeout 2-26 
Finding text A-5 

G 

GDT slots, displaying free amount 2-17 
Getting help 2-18, B-8 

H 

Hardware/Software requirements 1-2 
Help 2-18, B-8 

I 

I/O Result Segment (IORS) 2-39 

Identifying system call parameters on the stack 2-43 
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Interpreting system call parameters on the stack 2-43 
Invocation 1-3, 3-11 
IORS, displaying 2-39 
ISDM monitor commands 

B - bootstrap load A-3 

C - compare A-4 

D - Display A-4 

D3-12 

Directory A- 1 

E - exit A-4 

F-findA-5 

G - go A-5 

G 3-11, 3-12, 3-16 

I - port input A-5 

K - echo file A-5 

L - load A-6 

M - move A-6 

N - single instruction execution A-6 

N3-14 

O - port output A-7 

Overview A- 1 

P - print A-7 

Q - enable protection A-7 

R - load and go A-7 

S - substitute A-8 

X - examine/modify A-9 

X 3-13, 3-14, 3-16 

Y - symbols A-9 

J 

Job and decendent job tokens, displaying 2-20 

L 

Loading object files A-6, 7 
Locating running tasks 3-22 
Looping within D-MON386 B-6 

M 

Mailbox examination 3-21 

Manual Overview v 

Message Passing Coprocessor (MPC) 2-26, 2-28, 2-32 

Mode changing A-7 

Modifying the number base B-6 
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Monitor 1-1 
commands 

D-MON386 B-l 

iSDMA-1 
Moving blocks of memory A-6 
MPC 2-26, 2-28 

MPC input message queue 2-28 
MULTIBUS II 2-26, 2-28, 2-32 

o 

Object directory, displaying 2-13 
Objects, displaying 2-36, 3-20 

P 

Ports 

Displaying data A-5, B-7,9,11 

Entering data A-7, B-7,9,11 
Product Overview v, 1-1 
Program code execution 3-14 

Q 

Quitting the debugger 1-4, A-4 

R 

Re-entering the iSDM monitor 3-16 

Re-entering the monitor 3-11 

Reader level v 

Redirecting console output A-5 

Register contents, examining 3-13, 3-14 

Removing Breakpoints with D-MON386 B-ll 

Returning to your application 1-4 

s 

Sample debug session 3-1 

Searching for text A-5 

Setting breakpoints 1-3, 3-12, B-10 

Single-step execution A-6, e-step execution B-8 

Stack contents 2-43, 3-21 

Starting the debugger 1-3 

Strings, display limitations 2-47 

Support 1-2 

Symbol information, displaying A-9 

Syntax for debugger commands 1-4, 2-3 

Syntax for D-MON386 commands B-l 

System call information, displaying 2-10 

System call parameters on the stack, displaying 2-43 
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System requirements 1-2 

T 
Task system calls, displaying 2-74 
Task tokens, displaying 2-24 
Tokens, displaying 2-48, 3-20 

u 

Using PMON host software with D-MON386 B-8 
Using the debugger 1-4, 3-11 

V 

VB command 2-6 

VC command 2-10 

VD command 2-13 

Version number of D-MON386, displaying B-ll 

VF command 2-16 

VH command 2-18 

VJ command 2-20 

VK command 2-24 

VMF 2-26 

VMI 2-28 

VMO 2-32 

VO 2-36 

VO command 3-20 

VR command 2-39 

VS command 2-43 

VT command 

Buffer pool display 2-73 

Composite object display 2-60 

Extension object display 2-60 

Job display 2-49 

Mailbox display 2-54 

Mailbox display 3-21 

Region display 2-58 

Segment display 2-59 

Semaphore display 2-57 

Task display 2-51 
VT command 2-48 
VU command 2-74 

w 

Warm-start 1-4, 2-4 
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